cloud-host/ARCHITECTURE.md

# 🏗️ CloudHost PaaS — System Architecture

## Overview

CloudHost is a self-service PaaS that lets users deploy applications onto Kubernetes
clusters managed by a super admin. Source code (uploaded archive or git repo) is turned
into a container image **inside the cluster** with Kaniko, then rolled out via Helm. It
includes a full billing/wallet system, automated lifecycle management, managed
databases/services, Elasticsearch-backed logging, and a bilingual (Persian/English) panel.

Supported runtimes — each built from a platform-maintained `Dockerfile` template:
**Node.js, Laravel, Go, PHP, Python, Django, .NET**, and **WordPress** (official image).

---

## 🧱 High-Level Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        USERS / ADMINS  (Browser)                 │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTPS
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│              FRONTEND — Next.js 16 (App Router, bilingual)       │
│   Landing │ Auth (OTP) │ Deploy Wizard │ Dashboard │ Admin Panel │
└──────────────────────────┬──────────────────────────────────────┘
                           │ REST /api/v1 (JSON)
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                     BACKEND — NestJS 11                          │
│  Auth · Users · Admin · Applications · Deployments · Clusters    │
│  Build · Billing · Lifecycle · Snapshots · Tickets · Access ·    │
│  Notifications · Kubernetes/Helm/Registry                        │
└───┬───────────┬───────────────────┬───────────────┬─────────────┘
    │           │                   │               │
    ▼           ▼                   ▼               ▼
┌────────┐ ┌────────┐         ┌──────────┐ ┌──────────────────┐
│Postgres│ │ Redis  │         │ Registry │ │   Kubernetes     │
│  16    │ │(cache/ │         │  (:2)    │ │   Cluster(s)     │
│        │ │ Bull)  │         └──────────┘ │  ┌────────────┐  │
└────────┘ └────────┘                      │  │ Build Jobs │  │
                                           │  │  (Kaniko)  │  │
                                           │  └────────────┘  │
                                           │  Helm releases   │
                                           │  (user apps)     │
                                           └──────────────────┘
```

---

## 🧩 Module Overview

| Module | Purpose |
|--------|---------|
| **Auth** | Mobile-number + OTP (SMS) and password login; JWT access/refresh; Passport strategies; role guards |
| **Users** | User CRUD, profile, phone verification |
| **Admin** | Super-admin user-detail dashboard and operations |
| **Applications** | App CRUD, code upload (→ disk), git config, runtime/version metadata |
| **Application-migrations** | Import / migrate existing applications (Bull queue) |
| **Build** | `build.service` — runtime detection + per-runtime Dockerfile generation, Kaniko image builds inside K8s |
| **Deployments** | Deploy orchestration (build → Helm), history, stop/restart |
| **Kubernetes** | K8s API wrapper, Helm CLI wrapper, registry service |
| **Clusters** | Multi-cluster management, kubeconfig storage, default cluster |
| **Billing** | Wallet (deposit/deduct), transaction ledger, invoices, pricing catalog, coupons/discounts |
| **Lifecycle** | Interval scanner: auto-suspend expired apps, auto-delete after grace period |
| **Snapshots** | Application snapshot/backup & restore |
| **Tickets** | Support ticket system (technical/sales departments) |
| **Access** | Time-limited external access to app services via temporary NodePort grants (Bull queue) |
| **Notifications** | User-facing notifications |
| **Common / Config** | Shared enums, guards, decorators; env & TypeORM config |

---

## 🔧 Tech Stack

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

| Reason | Detail |
|--------|--------|
| **SSR & SEO** | Server-side rendering for fast initial loads and a public landing/blog |
| **App Router** | React Server Components, layouts, locale routing under `app/[lang]/` |
| **Bilingual** | `fa-IR` (default) + `en-US`; `middleware.ts` also splits landing vs authenticated panel |
| **React Query** | Server state, caching, polling for live build/deploy status |
| **Zustand** | Lightweight client auth store |
| **TypeScript** | End-to-end type safety |

### Backend: NestJS 11 (Node.js 20)

| Reason | Detail |
|--------|--------|
| **Modular** | Each domain is a self-contained module |
| **@kubernetes/client-node** | Direct K8s API interaction (Jobs, Deployments, logs, scale) |
| **Helm CLI** | Shell-out to helm for chart-based app deployments |
| **Bull (Redis)** | Async queues for service-access grants and application migrations |
| **TypeORM** | PostgreSQL ORM. `synchronize` is **development-only**; production schema changes ship as idempotent SQL migrations / `ALTER ... IF NOT EXISTS` |

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

| Reason | Detail |
|--------|--------|
| **No Docker daemon** | Builds run as unprivileged K8s Jobs in `cloudhost-builds` |
| **Runtime detection** | `detectRuntime()` infers Node.js / Laravel / WordPress from source files; the app may also pin a runtime explicitly |
| **Per-runtime Dockerfiles** | `generateDockerfile()` emits a tailored Dockerfile for Node.js, Laravel, WordPress, Go, PHP, Python, Django, or .NET |
| **WordPress** | Templated Dockerfile + custom entrypoint that merges `wp-content` |
| **Source ingestion** | Uploaded archives saved to disk and streamed into a per-build PVC (helper pod + `kubectl cp`); git repos cloned in-pod |
| **Registry push** | Native push to the in-cluster (insecure) registry |

### Deployment: Helm v3 Charts

| Reason | Detail |
|--------|--------|
| **Templated manifests** | One `cloudhost-app` chart handles all runtimes + attached services |
| **Rollback** | Built-in revision history |
| **Persistence** | DB/app PVCs and secrets use keep policies so they survive helm uninstall |
| **Ingress** | Traefik by default (k3s); `INGRESS_CLASS=nginx` for ingress-nginx |

---

## 🔄 Build & Deploy Flow

```
User triggers deploy (panel)
    │
    ▼
Backend runs the build-and-deploy pipeline, creating a Kubernetes Job in `cloudhost-builds`:

  ┌─ init: prepare source  (uploaded zip → disk → helper pod + `kubectl cp` → build PVC) ─┐
  │      …or…                                                                              │  → /workspace/source
  └─ init: git-clone       (clone repo; token injected into the URL for private repos) ───┘
                                   │
                                   ▼
  The platform detects the runtime and generates a Dockerfile for it
  (Node.js / Laravel / WordPress / Go / PHP / Python / Django / .NET)
                                   │
                                   ▼
  container: kaniko        → build image (cache per user) → push to in-cluster registry
                                   │
                                   ▼
        HelmService install/upgrade `cloudhost-app`
                                   │
                                   ▼
        Helm creates: Namespace, Deployment, Service, Ingress (+TLS), per-app
        DB/Redis/RabbitMQ, PVCs, Secrets, registry pull secret, log shipper
                                   │
                                   ▼
                 App live at https://<subdomain>.<PLATFORM_DOMAIN>
```

Notes:
- The build runs **inline** within the deploy request (it is not queued); build
  progress/logs are tracked in memory and polled by the frontend. This assumes a single
  active backend replica for an in-flight build.
- Bull/Redis queues are used by other subsystems (service-access grants, application
  migrations), not by the image build.

---

## 🔐 Security Architecture

- Mobile-OTP + password authentication; JWT access + refresh
- **Live** role/active-status enforcement — `JwtStrategy` reads the user from the DB each request
- Role-Based Access Control (`user` / `admin` / `technical` / `sales`)
- K8s namespace isolation per user; scoped ServiceAccounts
- Resource quotas & limit ranges; expandable per-app storage
- Secrets stored as K8s Secrets (env vars, DB creds)
- Input validation (class-validator), Helmet headers, Bcrypt password hashing

---

## 💰 Billing & Lifecycle Flow

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

DOCKED ── user removed the service; data retained until the plan expires
```

- **Billing cycles**: HOURLY | MONTHLY | YEARLY
- **Wallet**: deposits, deductions, refunds, gateway payments; invoices with coupons/discounts
- **Grace periods**: admin-configurable via the PlatformSettings entity (per cycle)
- **Lifecycle scanner**: runs on an interval (default 60s); suspends expired apps (scale to 0,
  data retained) and deletes them after the grace period

> ⚠️ The lifecycle scanner and other interval jobs assume a **single backend replica** —
> guard them (e.g. a Redis lock) before scaling the control plane horizontally.

---

## 📦 Helm Charts

### cloudhost-platform — control plane

Deploys the API, UI, PostgreSQL, and Redis into a namespace (default `cloudhost`).

| Template | Purpose |
|----------|---------|
| `backend-deployment.yaml` / `backend-service.yaml` / `backend-pvc.yaml` | NestJS API + uploads PVC |
| `frontend-deployment.yaml` / `frontend-service.yaml` | Next.js UI |
| `postgres-*.yaml` / `redis-*.yaml` | Control-plane database & queue |
| `ingress.yaml` | Frontend / API / panel host rules (+ TLS) |
| `secret.yaml` | JWT, DB, registry, SMS and other platform secrets |
| `migrations-configmap.yaml` / `migrations-job.yaml` | Optional SQL migration Job (`migrations.enabled`) |
| `namespace.yaml` / `_helpers.tpl` / `NOTES.txt` | Namespace + chart helpers |

Key values: `ingress.enabled`, `ingress.tls.*`, `ingress.frontend.host` / `ingress.api.host`,
`postgres.password`, `secrets.jwtSecret`, `migrations.enabled`.

### cloudhost-app — a single user application

| Template | Purpose |
|----------|---------|
| `deployment.yaml` | App pod (imagePullSecret, probes, WordPress volumes, env) |
| `service.yaml` / `ingress.yaml` | ClusterIP + ingress with TLS |
| `secret.yaml` | User env vars as a K8s Secret |
| `db-deployment.yaml` / `db-service.yaml` / `db-pvc.yaml` / `db-secret.yaml` | Optional managed PostgreSQL/MySQL/MariaDB/MongoDB |
| `redis-deployment.yaml` / `rabbitmq-deployment.yaml` | Optional attached services |
| `app-storage-pvc.yaml` | App persistent storage |
| `storageclass.yaml` | Expandable StorageClass (created on demand) |
| `registry-pull-secret.yaml` | imagePullSecret for the in-cluster registry |
| `fluent-bit-configmap.yaml` / `log-shipper-configmap.yaml` / `_log-shipper.tpl` / `elasticsearch-credentials-secret.yaml` | Per-app log shipping to Elasticsearch |

### cloudhost-logging — observability

Elasticsearch / Kibana / Fluent-bit stack for centralized build and runtime logs
(also see `backend/k8s/logging/`).

---

## 📁 Project Structure

```
cloud-host/
├── ARCHITECTURE.md  README.md  RUNBOOK.fa.md  CHANGELOG.md  CONTRIBUTING.md
├── UPGRADE.md  UPGRADE.en.md   docker-compose.yml
├── backend/                         # NestJS 11 API
│   ├── Dockerfile
│   ├── helm/{cloudhost-platform, cloudhost-app, cloudhost-logging}/
│   ├── k8s/{logging, mail}/         # standalone manifests
│   ├── migrations/                  # SQL migrations (one-off Jobs in prod)
│   └── src/
│       ├── main.ts / app.module.ts
│       ├── auth/  users/  admin/    # OTP auth, users, super-admin dashboard
│       ├── applications/  application-migrations/
│       ├── deployments/             # orchestration (build → Helm)
│       ├── build/                   # build.service: runtime detection + per-runtime Dockerfiles + Kaniko
│       ├── kubernetes/              # K8s client, Helm, registry
│       ├── clusters/                # multi-cluster management
│       ├── billing/  lifecycle/  snapshots/  tickets/  access/  notifications/
│       ├── common/                  # enums, guards, decorators
│       └── config/                  # env + TypeORM config
└── frontend/                        # Next.js 16 (App Router, fa-IR / en-US)
    ├── Dockerfile                   # ARG NEXT_PUBLIC_API_URL
    └── src/
        ├── middleware.ts            # locale routing + landing/panel split
        ├── app/[lang]/{page, login, register, blog, dashboard/*}
        ├── components/  hooks/  lib/  types/
        └── i18n/                    # dictionaries, provider, switcher
```

---

## 🔮 Future Considerations

1. Per-app horizontal autoscaling (HPA) based on CPU/memory
2. WebSocket/SSE for real-time build log streaming (currently polled)
3. A Redis-backed build queue (so builds survive a replica restart and the control plane can scale out)
4. In-cluster image vulnerability scanning (report-only)
5. GitOps integration (e.g. ArgoCD) and git-push-to-deploy
6. Automated control-plane database backups (scheduled `pg_dump` + retention)
7. App marketplace with pre-built templates