cloud-host/ARCHITECTURE.md

# 🏗️ CloudHost PaaS — System Architecture

## Overview

CloudHost is a self-service PaaS platform that enables users to deploy **Node.js**, **Laravel**, and **WordPress** applications onto Kubernetes clusters managed by a super admin. It includes a full billing/wallet system, automated lifecycle management, and Helm-based deployments.

---

## 🧱 High-Level Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        USERS / ADMINS                           │
│                     (Browser / CLI)                              │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTPS
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                     FRONTEND (Next.js 14)                       │
│  ┌──────────┐  ┌───────────────┐  ┌──────────┐  ┌───────────┐  │
│  │  Auth UI │  │ Deploy Wizard │  │ Dashboard│  │Admin Panel│  │
│  └──────────┘  └───────────────┘  └──────────┘  └───────────┘  │
└──────────────────────────┬──────────────────────────────────────┘
                           │ REST API (JSON)
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    BACKEND (NestJS 10)                           │
│                                                                 │
│  ┌──────────┐  ┌──────────────┐  ┌────────────┐  ┌──────────┐  │
│  │Auth      │  │Applications  │  │Deployments │  │Clusters  │  │
│  │Module    │  │Module        │  │Module      │  │Module    │  │
│  └──────────┘  └──────────────┘  └────────────┘  └──────────┘  │
│                                                                 │
│  ┌──────────┐  ┌──────────────┐  ┌────────────┐  ┌──────────┐  │
│  │Billing   │  │Lifecycle     │  │Snapshots   │  │Tickets   │  │
│  │Module    │  │Module        │  │Module      │  │Module    │  │
│  └──────────┘  └──────────────┘  └────────────┘  └──────────┘  │
│                                                                 │
│  ┌──────────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ Kubernetes       │  │ Helm         │  │ Build            │   │
│  │ Service          │  │ Service      │  │ Service          │   │
│  └────────┬─────────┘  └──────┬───────┘  └──────┬───────────┘   │
└───────────┼───────────────────┼──────────────────┼───────────────┘
            │                   │                  │
    ┌───────▼────────┐  ┌──────▼────────┐  ┌──────▼────────┐
    │  Kubernetes    │  │  Helm CLI     │  │  Kaniko       │
    │  Cluster(s)   │  │  (v3)         │  │  (in-cluster) │
    └───────────────┘  └───────────────┘  └───────────────┘
```

---

## 🧩 Module Overview

| Module | Purpose |
|--------|---------|
| **Auth** | JWT access/refresh tokens, Passport strategies, role guards |
| **Users** | User CRUD, admin activate/deactivate, profile management |
| **Applications** | App CRUD, code upload (zip), metadata, runtime detection |
| **Build** | Kaniko-based image builds via BullMQ queue; auto-detects Node.js/Laravel/WordPress |
| **Kubernetes** | K8s API interactions — namespace, scale, delete, pod logs, build pods |
| **Helm** | Helm CLI wrapper — install/upgrade, rollback, uninstall, history |
| **Deployments** | Deployment lifecycle orchestration, history, stop/restart |
| **Clusters** | Multi-cluster management, kubeconfig storage, default cluster selection |
| **Billing** | Wallet system (deposit/deduct), transaction ledger, plan cost calculation |
| **Lifecycle** | Cron-based scanner: auto-suspend expired apps, auto-delete after grace period |
| **Snapshots** | Application snapshot/backup management |
| **Tickets** | Support ticket system for users |

---

## 🔧 Tech Stack

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

| Reason | Detail |
|--------|--------|
| **SSR & SEO** | Server-side rendering for fast initial loads |
| **App Router** | 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** | Server state management, caching, polling for live status |
| **Zustand** | Lightweight client state management (auth store) |

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

| Reason | Detail |
|--------|--------|
| **Modular architecture** | Each domain is a self-contained module |
| **TypeScript native** | Full type safety, shared interfaces with frontend |
| **@kubernetes/client-node** | Official K8s client for direct API interaction |
| **Helm CLI** | Shell-out to helm for chart-based deployments |
| **Bull/BullMQ** | Redis-backed job queues for async build pipelines |
| **TypeORM** | PostgreSQL ORM with entity-based schema |

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

| Reason | Detail |
|--------|--------|
| **No Docker daemon** | Builds inside K8s pods — no Docker-in-Docker |
| **Runtime detection** | Auto-detects Node.js, Laravel, WordPress from source files |
| **WordPress support** | Custom entrypoint script for wp-content merging |
| **Registry push** | Native push to insecure or authenticated registries |

### Deployment: Helm v3 Charts

| Reason | Detail |
|--------|--------|
| **Templated manifests** | Single chart handles Node.js, Laravel, WordPress |
| **Rollback support** | Built-in revision history and rollback |
| **Resource policies** | PVCs and secrets persist across helm uninstall |
| **Registry pull secrets** | Auto-created per namespace for insecure registries |

---

## 🔐 Security Architecture

- JWT Authentication (access + refresh tokens)
- Role-Based Access Control (User / Admin)
- K8s Namespace Isolation per user
- K8s RBAC — scoped ServiceAccounts
- Network Policies between namespaces
- Resource Quotas & Limit Ranges
- Secrets encryption (K8s Secrets)
- Input validation (class-validator on all DTOs)
- Helmet HTTP security headers
- Bcrypt password hashing (12 rounds)

---

## 🔄 Deployment Flow

```
User uploads code (zip)
    │
    ▼
API stores file + metadata in PostgreSQL
    │
    ▼
BullMQ build job queued
    │
    ▼
detectRuntime() → nodejs | laravel | wordpress
    │
    ▼
Generate Dockerfile per runtime
    │
    ▼
Kaniko Pod builds image → pushes to registry
    │
    ▼
HelmService.installOrUpgrade() with cloudhost-app chart
    │
    ▼
Helm creates: Namespace, Deployment, Service, Ingress,
  DB, PVC, Secrets, Registry Pull Secret, TLS cert
    │
    ▼
App live at https://<subdomain>.apps.cloudhost.ir
```

---

## 💰 Billing & Lifecycle Flow

```
ACTIVE ──(expires)──► SUSPENDED ──(grace)──► PENDING_DELETION ──► DELETED
  ▲                       │                        │
  └────── payment ────────┘                        │
  └────── payment (within grace) ──────────────────┘
```

- **Billing Cycles**: HOURLY | MONTHLY | YEARLY
- **Hourly plans**: auto-renew from wallet each hour
- **Grace periods**: admin-configurable via PlatformSettings table
- **Lifecycle Scanner**: runs every 60s (configurable)

---

## 🚀 Helm Chart: cloudhost-app

Single chart at `backend/helm/cloudhost-app/` handles all runtimes:

| Template | Purpose |
|----------|---------|
| `deployment.yaml` | App pod with imagePullSecrets, probes, WordPress volumes |
| `service.yaml` | ClusterIP (port 80 → app port) |
| `ingress.yaml` | Nginx ingress with cert-manager TLS |
| `secret.yaml` | User env vars as K8s Secret |
| `db-deployment.yaml` | PostgreSQL or MySQL with health probes |
| `db-service.yaml` | Database ClusterIP service |
| `db-pvc.yaml` | Database storage (resource-policy: keep) |
| `db-secret.yaml` | Database credentials (resource-policy: keep) |
| `wp-pvc.yaml` | WordPress wp-content PVC (resource-policy: keep) |
| `registry-pull-secret.yaml` | imagePullSecret for insecure registry |

---

## 📁 Project Structure

```
host/
├── ARCHITECTURE.md
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── docker-compose.yml
├── backend/
│   ├── Dockerfile
│   ├── package.json
│   ├── helm/cloudhost-app/       # Helm chart for user apps
│   ├── src/
│   │   ├── main.ts / app.module.ts
│   │   ├── auth/                 # JWT + Passport
│   │   ├── users/                # User management
│   │   ├── applications/         # App CRUD + upload
│   │   ├── deployments/          # Deploy orchestration
│   │   ├── clusters/             # Multi-cluster (admin)
│   │   ├── kubernetes/           # K8s client + Helm service
│   │   ├── build/                # Kaniko builds (BullMQ)
│   │   ├── billing/              # Wallet + transactions
│   │   ├── lifecycle/            # Auto-suspend/delete
│   │   ├── snapshots/            # App snapshots
│   │   └── tickets/              # Support tickets
│   └── templates/                # Legacy Handlebars (deprecated)
├── frontend/
│   ├── Dockerfile
│   ├── package.json
│   └── src/
│       ├── app/dashboard/        # Apps, deploy, admin pages
│       ├── components/
│       ├── lib/                  # API client, auth store
│       └── types/                # Shared TS interfaces
└── uploads/                      # User-uploaded code archives
```

---

## 🔮 Future Considerations

1. Custom domains with auto TLS via cert-manager
2. Horizontal Pod Autoscaler based on CPU/memory
3. WebSocket/SSE for real-time build log streaming
4. GitOps integration (ArgoCD)
5. Additional runtimes (Python, Go, Rust)
6. App marketplace with pre-built templates
7. Per-app resource consumption dashboards