# 🏗️ CloudHost PaaS — System Architecture

## Overview

CloudHost is a self-service PaaS platform that enables users to deploy Node.js and Laravel applications onto Kubernetes clusters managed by a super admin.

---

## 🧱 High-Level Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        USERS / ADMINS                           │
│                     (Browser / CLI)                              │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTPS
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                     FRONTEND (Next.js)                          │
│  ┌──────────┐  ┌───────────────┐  ┌──────────┐  ┌───────────┐  │
│  │  Auth UI │  │ Deploy Wizard │  │ Dashboard│  │Admin Panel│  │
│  └──────────┘  └───────────────┘  └──────────┘  └───────────┘  │
└──────────────────────────┬──────────────────────────────────────┘
                           │ REST API (JSON)
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    BACKEND (NestJS)                              │
│                                                                 │
│  ┌──────────┐  ┌──────────────┐  ┌────────────┐  ┌──────────┐  │
│  │Auth      │  │Applications  │  │Deployments │  │Clusters  │  │
│  │Module    │  │Module        │  │Module      │  │Module    │  │
│  └──────────┘  └──────────────┘  └────────────┘  └──────────┘  │
│                                                                 │
│  ┌──────────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ Kubernetes       │  │ Build        │  │ Logs &           │   │
│  │ Service          │  │ Service      │  │ Metrics Service  │   │
│  └────────┬─────────┘  └──────┬───────┘  └──────────────────┘   │
│           │                   │                                  │
└───────────┼───────────────────┼──────────────────────────────────┘
            │                   │
    ┌───────▼────────┐  ┌──────▼────────┐
    │  Kubernetes    │  │  Container    │
    │  Cluster(s)   │  │  Registry     │
    │               │  │  (Harbor/ECR) │
    │ ┌───────────┐ │  └───────────────┘
    │ │Namespace A│ │
    │ │ ┌─Pod────┐│ │
    │ │ │App     ││ │  ┌────────────────┐
    │ │ └────────┘│ │  │  PostgreSQL    │
    │ │ ┌─Pod────┐│ │  │  (Metadata DB) │
    │ │ │DB      ││ │  └────────────────┘
    │ │ └────────┘│ │
    │ └───────────┘ │
    │ ┌───────────┐ │
    │ │Namespace B│ │
    │ │ ...       │ │
    │ └───────────┘ │
    └───────────────┘

```

---

## 🔧 Tech Stack Justification

### Frontend: **Next.js 14 (App Router) + Tailwind CSS**

| Reason | Detail |
|--------|--------|
| **SSR & SEO** | Server-side rendering for fast initial loads |
| **App Router** | Modern React Server Components, layouts, loading states |
| **Tailwind CSS** | Rapid UI development, consistent design system |
| **TypeScript** | End-to-end type safety with shared types |
| **React Query** | Efficient server state management, caching, polling for live status |

### Backend: **NestJS (Node.js)**

| Reason | Detail |
|--------|--------|
| **Modular architecture** | Each domain (auth, apps, deployments, clusters) is a self-contained module |
| **TypeScript native** | Full type safety, shared interfaces with frontend |
| **Decorator-based** | Clean controller/service pattern, guards, interceptors |
| **@kubernetes/client-node** | Official K8s client for Node.js — direct API interaction |
| **Bull/BullMQ** | Redis-backed job queues for async build & deploy pipelines |
| **TypeORM** | Mature PostgreSQL ORM with migration support |

### Database: **PostgreSQL**

| Reason | Detail |
|--------|--------|
| **ACID compliance** | Critical for deployment state tracking |
| **JSON columns** | Store flexible config/metadata without schema changes |
| **Mature ecosystem** | Battle-tested, excellent TypeORM support |
| **Scalability** | Read replicas, partitioning for growth |

### Build System: **Kaniko (in-cluster)**

| Reason | Detail |
|--------|--------|
| **No Docker daemon** | Builds images inside K8s pods — no Docker-in-Docker security issues |
| **Registry push** | Native push to any OCI-compatible registry |
| **Caching** | Layer caching for faster rebuilds |

### Container Registry: **Harbor (self-hosted) or cloud-managed (ECR/GCR/ACR)**

| Reason | Detail |
|--------|--------|
| **Private images** | User apps must not be publicly accessible |
| **Vulnerability scanning** | Harbor provides built-in image scanning |
| **Multi-tenancy** | Project-based access control |

### Queue System: **Redis + BullMQ**

| Reason | Detail |
|--------|--------|
| **Async builds** | Image builds are long-running — must not block API |
| **Retries** | Failed builds auto-retry with backoff |
| **Progress tracking** | Real-time build status updates |

---

## 🔐 Security Architecture

```
┌─────────────────────────────────────────┐
│              Security Layers            │
├─────────────────────────────────────────┤
│                                         │
│  1. JWT Authentication (access/refresh) │
│  2. Role-Based Access (User / Admin)    │
│  3. K8s Namespace Isolation per user    │
│  4. K8s RBAC — scoped ServiceAccounts   │
│  5. Network Policies between namespaces │
│  6. Resource Quotas & Limit Ranges      │
│  7. Secrets encryption (K8s Secrets)    │
│  8. Input validation on all user inputs │
│  9. Rate limiting on API endpoints      │
│                                         │
└─────────────────────────────────────────┘
```

---

## 🔄 Deployment Flow

```
User uploads code ──► API receives ──► Store metadata in PostgreSQL
                                              │
                                              ▼
                                     Queue build job (BullMQ)
                                              │
                                              ▼
                                     Kaniko Pod builds image
                                              │
                                              ▼
                                     Push to Container Registry
                                              │
                                              ▼
                                     Generate K8s manifests from templates
                                              │
                                              ▼
                                     Apply to target cluster via K8s API
                                              │
                                              ▼
                                     Create: Namespace, Deployment, Service,
                                             Ingress, PVC, DB, Secrets
                                              │
                                              ▼
                                     Update deployment status in DB
                                              │
                                              ▼
                                     User sees live status in dashboard
```

---

## 📁 Project Structure

```
host/
├── ARCHITECTURE.md
├── README.md
├── docker-compose.yml
├── backend/                    # NestJS API
│   ├── src/
│   │   ├── main.ts
│   │   ├── app.module.ts
│   │   ├── common/            # Shared utilities, guards, decorators
│   │   ├── config/            # Environment configuration
│   │   ├── auth/              # JWT auth, strategies, guards
│   │   ├── users/             # User management
│   │   ├── applications/      # App CRUD, code upload
│   │   ├── deployments/       # Deployment lifecycle
│   │   ├── clusters/          # K8s cluster management (admin)
│   │   ├── kubernetes/        # K8s client, manifest generation
│   │   ├── build/             # Image build pipeline
│   │   └── database/          # TypeORM entities, migrations
│   ├── templates/             # K8s YAML templates (Handlebars)
│   ├── Dockerfile
│   ├── package.json
│   └── tsconfig.json
├── frontend/                   # Next.js App
│   ├── src/
│   │   ├── app/               # App Router pages
│   │   ├── components/        # Reusable UI components
│   │   ├── lib/               # API client, utilities
│   │   ├── hooks/             # Custom React hooks
│   │   └── types/             # TypeScript interfaces
│   ├── Dockerfile
│   ├── package.json
│   └── tailwind.config.ts
└── k8s/                        # Platform's own K8s deployment
    ├── base/
    └── overlays/
```

---

## 🚀 Future Scaling Considerations

1. **Multi-cluster support** — Deploy to different clusters/regions
2. **Custom domains** — Let users bring their own domains with auto TLS
3. **Horizontal Pod Autoscaler** — Auto-scale based on metrics
4. **WebSocket/SSE** — Real-time build logs streaming
5. **Plugin system** — Support Python, Go, Rust runtimes
6. **Marketplace** — Pre-built app templates (WordPress, etc.)
7. **Billing integration** — Usage-based billing per resource consumption
8. **GitOps** — ArgoCD integration for declarative deployments