keyhan
5f77c07183
- ARCHITECTURE.md: all modules, Helm charts, billing/lifecycle flow, WordPress - README.md: updated features, API endpoints, configuration, project structure - CHANGELOG.md: full changelog for all unreleased changes - CONTRIBUTING.md: commit conventions, documentation requirements, PR checklist
12 KiB
12 KiB
🏗️ 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
- Custom domains with auto TLS via cert-manager
- Horizontal Pod Autoscaler based on CPU/memory
- WebSocket/SSE for real-time build log streaming
- GitOps integration (ArgoCD)
- Additional runtimes (Python, Go, Rust)
- App marketplace with pre-built templates
- Per-app resource consumption dashboards