cloud-host/ARCHITECTURE.md

🏗️ 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