Architecture Overview

LusterCMS follows a modern, cloud-native, multi-tenant architecture designed for enterprise SaaS deployments. All services run on Kubernetes (K3s) for production workloads.

System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Clients                                         │
│   Browser  │  Mobile App  │  External API  │  CLI  │  Theme Frontends       │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    Nginx (Reverse Proxy + SSL Termination)                   │
│                    + Let's Encrypt (certbot) for SSL                        │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
┌───────────────────────────────────┴───────────────────────────────────────┐
│                         KUBERNETES CLUSTER (K3s)                           │
│                                                                            │
│  ┌──────────────────────────────────────────────────────────────────────┐ │
│  │                 NAMESPACE: lustercms-core                             │ │
│  │                                                                       │ │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │ │
│  │  │  Backend    │ │  Frontend   │ │ PostgreSQL  │ │    Redis    │    │ │
│  │  │  (FastAPI)  │ │  (Next.js)  │ │   (Core)    │ │   (Cache)   │    │ │
│  │  │  2 replicas │ │  2 replicas │ │  Main DB    │ │             │    │ │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘    │ │
│  │                                                                       │ │
│  │  ┌─────────────┐                                                     │ │
│  │  │   MinIO     │  Core DB contains: users, orgs, billing, RBAC,     │ │
│  │  │ (S3 Media)  │  theme marketplace, global settings                │ │
│  │  └─────────────┘                                                     │ │
│  └──────────────────────────────────────────────────────────────────────┘ │
│                                                                            │
│  ┌──────────────────────────────────────────────────────────────────────┐ │
│  │                    NAMESPACE: themes                                  │ │
│  │                                                                       │ │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐      │ │
│  │  │   theme-org-A   │  │   theme-org-B   │  │   theme-org-N   │      │ │
│  │  │  (ecommerce)    │  │  (starter)      │  │   (any)         │      │ │
│  │  │                 │  │                 │  │                 │      │ │
│  │  │ tenant-a.       │  │ tenant-b.       │  │ client-domain.  │      │ │
│  │  │ lustercms.com   │  │ lustercms.com   │  │ com             │      │ │
│  │  └─────────────────┘  └─────────────────┘  └─────────────────┘      │ │
│  └──────────────────────────────────────────────────────────────────────┘ │
│                                                                            │
│  ┌──────────────────────────────────────────────────────────────────────┐ │
│  │           NAMESPACE: tenant-ORG_ID (per-org isolation)                │ │
│  │                                                                       │ │
│  │  ┌─────────────────────────────────────────────────────────────────┐ │ │
│  │  │  PostgreSQL POD (isolated tenant data: content, media, etc.)    │ │ │
│  │  └─────────────────────────────────────────────────────────────────┘ │ │
│  └──────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────┘

Infrastructure Components

Component	Technology	Location	Purpose
Backend API	FastAPI + Strawberry GraphQL	K8s: lustercms-core	API, business logic
Admin Frontend	Next.js 14	K8s: lustercms-core	Admin panel UI
Core Database	PostgreSQL + pgvector	K8s: lustercms-core	Users, orgs, RBAC
Cache	Redis	K8s: lustercms-core	Sessions, caching
Media Storage	MinIO (S3)	K8s: lustercms-core	File uploads
Theme Deployments	Next.js	K8s: themes	Per-org websites
Tenant Databases	PostgreSQL	K8s: tenant-ORG_SLUG	Content isolation
SSL/TLS	Let's Encrypt + certbot	Nginx (host)	HTTPS certificates
Reverse Proxy	Nginx	Host	Routing, SSL termination

Multi-Tenant Isolation Model

┌─────────────────────────────────────────────────────────────────────────────┐
│                          PLATFORM (Superadmin)                               │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                        ADMIN / AGENCY                                    ││
│  │  ┌───────────────────────────────────────────────────────────────────┐  ││
│  │  │                     ORGANIZATION                                   │  ││
│  │  │                                                                    │  ││
│  │  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │  ││
│  │  │  │  Database   │  │  S3 Bucket  │  │  K8s Theme  │               │  ││
│  │  │  │ (isolated)  │  │ org-SLUG-   │  │    Pod      │               │  ││
│  │  │  │             │  │   media     │  │             │               │  ││
│  │  │  └─────────────┘  └─────────────┘  └─────────────┘               │  ││
│  │  │                                                                    │  ││
│  │  └───────────────────────────────────────────────────────────────────┘  ││
│  └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘

Golden Rule: "Everything down, nothing up"

Superadmins see all organizations and data
Agency admins see their org + all descendant/client organizations
Regular users see only their own organization

Deployment Architecture

GitHub Actions CI/CD

┌─────────────────────────────────────────────────────────────────────────┐
│                        GitHub Actions Workflow                           │
│                                                                          │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────────────┐ │
│  │   Build     │    │   Push to   │    │    Deploy to K8s            │ │
│  │  Frontend   │ →  │    GHCR     │ →  │  - Import image to K3s      │ │
│  │  Backend    │    │  (Docker)   │    │  - kubectl rollout restart  │ │
│  └─────────────┘    └─────────────┘    └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘

Traffic Flow

User Request
     │
     ▼
┌─────────────────┐
│     Nginx       │  *.lustercms.com
│  (SSL + Proxy)  │
└─────────────────┘
     │
     ├── admin.lustercms.com/api/* ───→ K8s Backend (ClusterIP)
     ├── admin.lustercms.com/* ───────→ K8s Frontend (ClusterIP)
     ├── tenant-a.lustercms.com ──────→ K8s theme-org-A (ClusterIP)
     ├── tenant-b.lustercms.com ──────→ K8s theme-org-B (ClusterIP)
     └── docs.lustercms.com ──────────→ Static files

Frontend Architecture

frontend/
├── app/                    # Next.js App Router
│   ├── admin/              # Admin panel pages
│   ├── api/                # API routes
│   └── (public)/           # Public pages
├── components/             # React components
├── graphql/                # GraphQL queries/mutations
├── hooks/                  # Custom React hooks
├── lib/                    # Utilities
└── types/                  # TypeScript types

Backend Architecture

core/
├── api/                    # API layer (GraphQL, REST)
├── auth/                   # Authentication & RBAC
│   └── org_access.py       # Multi-tenant access control ("golden rule")
├── content/                # Content management
├── media/                  # Media handling
│   ├── services.py         # Media upload/process
│   ├── storage.py          # Local storage adapter
│   └── s3_storage.py       # MinIO S3 storage (enterprise)
├── tenants/                # Multi-tenant management
│   ├── registration_wizard_service.py
│   ├── provisioning.py     # Database provisioning
│   ├── k8s_provisioner.py  # K8s namespace/DB provisioning
│   └── routes.py           # Organization APIs
├── themes/                 # Theme management
│   └── service.py          # Theme switching with K8s deploy
├── theme_marketplace/      # Theme deployment
│   └── deployer_k8s.py     # Kubernetes theme deployer
├── ai/                     # AI services
├── plugins/                # Plugin system
└── hooks.py                # Hook definitions

plugins/
├── calendar/               # Calendar plugin
├── ecommerce/              # E-commerce plugin
├── linkedin/               # LinkedIn plugin
└── ...

infrastructure/
├── k8s/                    # Kubernetes manifests
│   ├── core/               # Core services (backend, frontend, db, redis, minio)
│   ├── themes/             # Per-org theme deployment templates
│   └── tenant-template/    # Per-tenant namespace template
└── contabo/                # Legacy Docker Compose (deprecated)

Data Flow

Request → Frontend or API client
Authentication → JWT validation
Authorization → Permission check + org_id validation
Business Logic → Service layer
Data Access → SQLAlchemy ORM (main or tenant DB)
Response → JSON/GraphQL

Registration Flow

Two registration paths based on account type:

                    ┌─────────────────────┐
                    │   Registration      │
                    │   (project_type:    │
                    │   website/ecommerce)│
                    └─────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│      ORGANIZATION       │     │        AGENCY           │
│    (Auto-provisioned)   │     │   (Requires approval)   │
└─────────────────────────┘     └─────────────────────────┘
              │                               │
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│  1. Create user (pending)│     │ 1. Create user (pending)│
│  2. Create organization  │     │ 2. Create organization  │
│  3. Provision tenant     │     │    (PENDING_REVIEW)     │
│     namespace + DB (K8s) │     │ 3. Wait for approval    │
│  4. Assign theme         │     │ 4. On approve: provision│
│  5. Seed demo data       │     │ 5. Deploy to K8s        │
│  6. Deploy theme to K8s  │     │ 6. Send welcome email   │
│  7. Configure nginx      │     │                         │
│  8. Send welcome email   │     │                         │
└─────────────────────────┘     └─────────────────────────┘

Theme and plugin selection based on project_type:

Website: luster-starter theme + SEO Assistant plugin
E-commerce: luster-ecommerce-starter theme + E-commerce + SEO plugins

Theme Marketplace & Deployment

Per-organization theme deployments for full isolation:

┌─────────────────────────────────────────────────────────────────┐
│                   Kubernetes Cluster                             │
│                   (themes namespace)                             │
│                                                                  │
│  ┌─────────────────┐  ┌─────────────────┐                       │
│  │  theme-org-A    │  │  theme-org-B    │                       │
│  │  (ecommerce)    │  │  (starter)      │                       │
│  │                 │  │                 │                       │
│  │ ┌─────────────┐ │  │ ┌─────────────┐ │                       │
│  │ │ Deployment  │ │  │ │ Deployment  │ │                       │
│  │ │ Service     │ │  │ │ Service     │ │                       │
│  │ │ HPA (Pro+)  │ │  │ │ HPA (Pro+)  │ │                       │
│  │ └─────────────┘ │  │ └─────────────┘ │                       │
│  └─────────────────┘  └─────────────────┘                       │
│                                                                  │
│  URLs (via nginx):                                               │
│  - tenant-a.lustercms.com → theme-org-A                         │
│  - tenant-b.lustercms.com → theme-org-B                         │
│  - client-domain.com → theme-org-N (custom domains)             │
└─────────────────────────────────────────────────────────────────┘

Features:

Per-organization resource quotas (Starter/Pro/Enterprise tiers)
Horizontal Pod Autoscaling (Pro/Enterprise)
Theme switching with zero-downtime redeployment
Automatic subdomain provisioning

Media Storage (MinIO S3)

Enterprise-grade, multi-tenant media storage using S3-compatible MinIO:

┌─────────────────────────────────────────────────────────────┐
│                     MinIO S3 Storage                         │
│                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │org-A-media  │  │org-B-media  │  │org-N-media  │  ...    │
│  │  /YYYY/MM/  │  │  /YYYY/MM/  │  │  /YYYY/MM/  │         │
│  │    img.jpg  │  │    doc.pdf  │  │    vid.mp4  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

Each organization gets an isolated bucket (org-SLUG-media), ensuring:

Complete data isolation between tenants
RBAC-aware file listing (agency admins see their org + clients)
Automatic bucket provisioning on registration

Security

JWT authentication with role-based claims
Multi-tenant RBAC ("everything down, nothing up")
Per-organization database isolation (separate PostgreSQL per tenant)
Per-organization S3 bucket isolation
Input validation (Pydantic)
SQL injection prevention (ORM)
XSS protection (React)
HTTPS/SSL everywhere (Let's Encrypt + certbot)

Key Technologies

Layer	Technology
Container Orchestration	Kubernetes (K3s)
Backend	Python 3.11, FastAPI, Strawberry GraphQL
Frontend	Next.js 14, React 18, TypeScript
Database	PostgreSQL 16 + pgvector
Cache	Redis 7
Storage	MinIO (S3-compatible)
CI/CD	GitHub Actions
SSL	Let's Encrypt + certbot
Reverse Proxy	Nginx

System Architecture​

Infrastructure Components​

Multi-Tenant Isolation Model​

Deployment Architecture​

GitHub Actions CI/CD​

Traffic Flow​

Frontend Architecture​

Backend Architecture​

Data Flow​

Registration Flow​

Theme Marketplace & Deployment​

Media Storage (MinIO S3)​

Security​

Key Technologies​