TeezU Platform Architecture

🏗️ System Overview — v3.0

TeezU v3.0 is gebouwd als een pnpm monorepo met Turborepo voor build-orchestratie. De codebase is opgesplitst in apps/, services/ en packages/ voor maximale herbruikbaarheid en type-safety over de volledige stack.

TeezU Monorepo (pnpm workspaces + Turborepo)
│
├── apps/
│   └── web/                  → React 19 + Vite 7 + Tailwind CSS 4
│                               (main PWA frontend, mobile-first)
│
├── services/
│   └── api/                  → Fastify 5 + Drizzle ORM + PostgreSQL 16
│                               (backend REST API + Socket.IO)
│
└── packages/
    ├── ui/                   → Shared React components (Radix UI + CVA)
    ├── types/                → Shared TypeScript types + Zod schemas
    ├── api-client/           → Type-safe API client (fetch wrapper)
    └── utils/                → Shared utilities (formatters, helpers)

┌─────────────────────────────────────────────────────────┐
│                  FRONTEND  (apps/web)                   │
│  React 19 · Vite 7 · TypeScript 5.9 · Tailwind CSS 4   │
│  Zustand 5 · TanStack Query v5 · React Hook Form + Zod  │
│  Socket.IO Client · WebRTC · PWA (VitePWA)              │
└────────────────────────────┬────────────────────────────┘
                             ↕  REST + WebSocket
┌────────────────────────────┴────────────────────────────┐
│                  BACKEND  (services/api)                │
│  Node.js 22 · Fastify 5 · TypeScript 5.9                │
│  Drizzle ORM · Lucia Auth · Socket.IO · Zod validation  │
└──────┬──────────────┬──────────────┬────────────────────┘
       ↕              ↕              ↕
┌──────┴──────┐ ┌─────┴──────┐ ┌────┴──────────────────┐
│ PostgreSQL  │ │   Redis    │ │  MongoDB               │
│     16      │ │  (RT state │ │  (AI configs /         │
│ (relational)│ │  sessions) │ │   chat logs)           │
└─────────────┘ └────────────┘ └────────────────────────┘
       ↕                              ↕
┌──────┴──────┐             ┌─────────┴──────────────────┐
│  S3 /       │             │  Vector DB                 │
│  Cloudinary │             │  (Pinecone / Weaviate)     │
│  (media)    │             │  (AI matching / search)    │
└─────────────┘             └────────────────────────────┘

⚛️ Frontend Architecture — apps/web

Core Stack

• React 19 — UI framework (concurrent features)
• TypeScript 5.9 — Type safety
• Vite 7 — Ultra-fast build tool + HMR
• Tailwind CSS 4 — Utility-first styling
• React Router v7 — Client-side routing

State Management

• Zustand 5 — Global state (slices: user / wallet / ui / chat)
• TanStack Query v5 — Server state + caching
• React Hook Form + Zod — Form validation
• Socket.IO Client — Real-time sync

Real-time & Media

• Socket.IO — Chat, notifications, live events
• WebRTC — Video/voice livestreams
• MediaStream API — Camera & microphone
• VitePWA — Service worker + offline support

UI & Performance

• Radix UI — Accessible headless components (packages/ui)
• CVA — Class Variance Authority for variants
• React.lazy + Suspense — Route-level code splitting
• Virtual scrolling — Performance for long lists

Zustand Store Slices

useAppStore  (persist middleware for ui slice)
├── user   slice → { profile, role, session }        actions: setUser, clearUser
├── wallet slice → { balance, transactions }          actions: updateWallet
├── ui     slice → { sidebar, language, theme }       actions: toggleSidebar, setLanguage
└── chat   slice → { activeRoom, messages, typing }   actions: sendMessage, setTyping

🖥️ Backend Architecture — services/api

Core Stack

• Node.js 22 — Runtime (LTS)
• Fastify 5 — High-performance HTTP server
• TypeScript 5.9 — Strict type safety
• Socket.IO — Real-time WebSocket layer
• Zod — Runtime schema validation

Database & ORM

• PostgreSQL 16 — Primary relational DB
• Drizzle ORM — Type-safe SQL-first ORM
• Redis — Real-time state, sessions, pub/sub
• MongoDB — AI configs & chat logs
• Pinecone / Weaviate — Vector DB for AI matching

Authentication

• Lucia Auth — Session-based authentication
• bcrypt — Password hashing
• RBAC middleware — Role-based access control
• 2FA — Two-factor authentication (TOTP)

Media & Storage

• S3 / Cloudinary — Media file storage
• Sharp — Image processing & thumbnails
• FFmpeg — Video transcoding
• CDN — Global asset distribution

🔄 Data Flow

REST API Flow (Fastify 5)

Client (TanStack Query) → HTTP Request → Fastify Route
  ↓
Lucia Auth Middleware → RBAC Role Check
  ↓
Zod Schema Validation → Controller → Service Layer
  ↓
Drizzle ORM → PostgreSQL 16
  ↓
Response ← JSON Serialize ← Query Result

Real-time Flow (Socket.IO + Redis)

Client (Socket.IO) ↔ Fastify WebSocket Server
  ↓                              ↓
Room / Namespace Management   Redis Pub/Sub (multi-instance)
  ↓                              ↓
Event Handlers ← → Chat / Stream Service ← → PostgreSQL
  ↓
Live State pushed to all connected clients in room

Media Upload Flow

Client → Multipart Upload → Fastify Multipart Plugin
  ↓
Zod MIME / Size Validation
  ↓
Sharp (image resize) / FFmpeg (video transcode)
  ↓
S3 / Cloudinary Upload → CDN distribution
  ↓
Drizzle ORM → PostgreSQL (media record + metadata)

Auth Session Flow (Lucia Auth)

Login Request → Zod validate → bcrypt verify password
  ↓
Lucia Auth → create Session → store in PostgreSQL
  ↓
Session cookie (HttpOnly, Secure) → Client
  ↓
Subsequent requests → Lucia validateSession() → user context
  ↓
RBAC middleware → check role → allow / deny

🗄️ Database Schema — PostgreSQL 16 + Drizzle ORM

Het primaire schema draait op PostgreSQL 16 via Drizzle ORM (SQL-first, volledig type-safe). AI-configs en chat logs leven in MongoDB. Real-time state en sessies in Redis. Matching- en zoekfeatures gebruiken een Vector DB (Pinecone / Weaviate).

┌───────────────────────────────────────────────┐
│         CORE — PostgreSQL 16                  │
├───────────────────────────────────────────────┤
│ • users            (id, role, email, …)       │
│ • profiles         (bio, avatar, cover, …)    │
│ • sessions         (Lucia Auth sessions)      │
│ • consent_records  (age verification, ToS)    │
└───────────────────────────────────────────────┘

┌───────────────────────────────────────────────┐
│         RBAC & ACCESS                         │
├───────────────────────────────────────────────┤
│ • roles            (super_admin … viewer)     │
│ • permissions      (resource + action)        │
│ • user_roles       (join table)               │
└───────────────────────────────────────────────┘

┌───────────────────────────────────────────────┐
│         SOCIAL & CONTENT                      │
├───────────────────────────────────────────────┤
│ • follows          (follower_id, creator_id)  │
│ • posts            (type, media_url, …)       │
│ • media            (s3_key, cdn_url, mime)    │
│ • stories          (expires_at, …)            │
│ • comments / likes                            │
└───────────────────────────────────────────────┘

┌───────────────────────────────────────────────┐
│         STREAMING & LIVE                      │
├───────────────────────────────────────────────┤
│ • streams          (creator_id, status, …)    │
│ • stream_viewers   (join, view_duration)      │
│ • stream_events    (type, payload, ts)        │
└───────────────────────────────────────────────┘

┌───────────────────────────────────────────────┐
│         COMMERCE & WALLET                     │
├───────────────────────────────────────────────┤
│ • wallets          (user_id, balance)         │
│ • transactions     (type, amount, status)     │
│ • subscriptions    (tier, start, end)         │
│ • tips             (from, to, token_amount)   │
│ • payouts          (creator_id, status)       │
└───────────────────────────────────────────────┘

┌───────────────────────────────────────────────┐
│         CHAT  — MongoDB                       │
├───────────────────────────────────────────────┤
│ • chat_messages    (room_id, sender, content) │
│ • ai_configs       (persona, model settings)  │
│ • chat_logs        (session replay, metadata) │
└───────────────────────────────────────────────┘

👥 RBAC — Role-Based Access Control

Alle gebruikers hebben één of meerdere rollen. Rechten worden afgedwongen via Fastify middleware op elke route.

🛡️ Super Admin

Volledige systeemtoegang. Platform configuratie, user management, alle data.

⚙️ Admin

Content moderatie, creator goedkeuring, rapportage en analytics.

🔍 Moderator

Chat moderatie, content review, melden afhandelen.

🎬 Creator / Creator+

Live streams starten, content uploaden, betaalde abonnementen aanbieden, chattools gebruiken.

🤝 Provider

Externe dienstverleners die content of services aanbieden via het platform.

👤 Member (basic / plus / premium / elite)

Geregistreerde gebruikers met gestaffelde toegang. Elite heeft volledige feature-set.

👁️ Viewer

Anonieme of niet-geauthenticeerde bezoeker. Alleen publiek zichtbare content.

⚙️ Microservices

De backend is intern opgedeeld in logische service-domeinen die elk hun eigen verantwoordelijkheid hebben. Ze communiceren via interne function calls binnen services/api en via Redis pub/sub voor async events.

services/api/src/services/
├── auth/        → Lucia Auth sessions, login, logout, 2FA
├── user/        → Profiles, follows, RBAC role management
├── stream/      → Live stream lifecycle, HLS, viewer state
├── chat/        → Rooms, messages, Socket.IO events
├── token-tip/   → Token economy, tip flows, gamification
├── wallet/      → Balances, transactions, payout requests
├── ai/          → AI persona configs, matching, vector search
├── consent/     → Age verification, ToS acceptance, GDPR
└── media/       → Upload, processing (Sharp/FFmpeg), CDN

Auth Service

• Lucia Auth session management
• bcrypt password hashing
• TOTP two-factor auth

Stream Service

• HLS live stream management
• Viewer count via Redis
• Stream events & analytics

AI Service

• AI persona configuration
• Vector search (Pinecone/Weaviate)
• Smart matching algoritme

📈 Scalability Strategy

Horizontal Scaling

• Load balancer (Nginx / cloud LB)
• Meerdere Fastify instances
• Stateless design (sessies in Redis)
• Turborepo remote caching
• Docker containers (auto-scaling)

Caching

• Redis voor sessies & real-time state
• TanStack Query client-side cache
• CDN voor media assets
• VitePWA StaleWhileRevalidate (assets)
• VitePWA NetworkFirst (API calls)

Database

• PostgreSQL 16 read replicas
• Drizzle connection pooling
• Index-strategie per domein
• MongoDB sharding voor chat logs
• Vector DB auto-indexing

🔒 Security Measures

Authentication & Authorization

• Lucia Auth — session-based (geen JWT in localStorage)
• RBAC middleware — role-based access op elke route
• bcrypt — wachtwoord hashing (cost factor 12)
• TOTP 2FA — twee-factor authenticatie

Data Protection

• HTTPS/TLS 1.3 end-to-end encryptie
• PostgreSQL encryption at rest
• HttpOnly + Secure session cookies
• GDPR compliance + consent records

API Security

• Zod — runtime validatie op alle inputs
• Fastify rate limiting — per IP en per user
• CORS whitelist configuratie
• SQL injection preventie via Drizzle (parameterized queries)

Monitoring & Compliance

• Error tracking (Sentry)
• Performance monitoring (Fastify metrics)
• Security audit logs (alle auth events)
• Automated DB backups + point-in-time recovery

🚀 Infrastructure & CI/CD

Monorepo Tooling

• pnpm workspaces — package management
• Turborepo — build orchestratie + remote caching
• TypeScript project references — incremental builds
• ESLint + Prettier — code kwaliteit

Deployment

• Docker — containerized services
• CI/CD pipeline — automatische deploys
• CDN — globale asset distributie
• Horizontal scaling — auto-scaling API pods

Turborepo Pipeline

turbo run build
  ├── packages/types     → compile TS types (shared)
  ├── packages/utils     → compile utilities
  ├── packages/ui        → build component library
  ├── packages/api-client→ generate type-safe client
  ├── services/api       → build Fastify server
  └── apps/web           → Vite 7 production build → CDN deploy