keyhan
229 lines
12 KiB
Markdown
229 lines
12 KiB
Markdown
# 🏗️ 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
|