Platform Domain

The Platform domain covers the foundational architecture including multi-tenant isolation, permission management, service registry, and cross-cutting concerns.

Platform Architecture Overview

graph TB
    subgraph "Client Layer"
        WEB[Web App]
        MOBILE[Mobile App]
        API_CLIENT[API Clients]
    end

    subgraph "API Layer"
        TRPC[TRPC Router]
        REST[REST API]
        GRAPHQL[GraphQL]
    end

    subgraph "Auth & Security"
        AUTH[Authentication]
        RBAC[RBAC System]
        TENANT_CTX[Tenant Context]
    end

    subgraph "Business Layer"
        SERVICES[Service Registry]
        DOMAINS[Domain Services]
    end

    subgraph "Data Layer"
        PRISMA[Prisma ORM]
        CACHE[Redis Cache]
        DB[(PostgreSQL)]
    end

    subgraph "Infrastructure"
        QUEUE[Job Queues]
        STORAGE[File Storage]
        EMAIL[Email Service]
    end

    WEB --> TRPC
    MOBILE --> REST
    API_CLIENT --> GRAPHQL

    TRPC --> AUTH
    REST --> AUTH
    GRAPHQL --> AUTH

    AUTH --> RBAC
    RBAC --> TENANT_CTX

    TENANT_CTX --> SERVICES
    SERVICES --> DOMAINS

    DOMAINS --> PRISMA
    DOMAINS --> CACHE
    PRISMA --> DB

    DOMAINS --> QUEUE
    DOMAINS --> STORAGE
    DOMAINS --> EMAIL

    style SERVICES fill:#e1f5fe
    style RBAC fill:#fff3e0
    style TENANT_CTX fill:#e8f5e9

Multi-Tenant Data Model

erDiagram
    TENANT ||--o{ SITE : has
    TENANT ||--o{ USER_TENANT : has_members
    USER ||--o{ USER_TENANT : belongs_to
    USER_TENANT }o--|| ROLE : has
    ROLE ||--o{ ROLE_PERMISSION : grants
    PERMISSION ||--o{ ROLE_PERMISSION : granted_by

    SITE ||--o{ SITE_CONFIG : configured_by
    SITE ||--o{ DOMAIN : has

    TENANT {
        string id PK
        string name
        string slug
        enum status
        json settings
        timestamp createdAt
    }

    SITE {
        string id PK
        string tenantId FK
        string name
        string primaryDomain
        json configuration
        boolean isActive
    }

    USER {
        string id PK
        string email
        string name
        json profile
        timestamp lastLogin
    }

    USER_TENANT {
        string id PK
        string userId FK
        string tenantId FK
        string roleId FK
        boolean isOwner
        timestamp joinedAt
    }

    ROLE {
        string id PK
        string tenantId FK
        string name
        string description
        boolean isSystem
    }

    PERMISSION {
        string id PK
        string code
        string name
        string category
    }

Tenant Hierarchy

flowchart TB
    subgraph "Platform Level"
        PLATFORM[Platform Admin]
        SYS_CONFIG[System Configuration]
    end

    subgraph "Tenant Level"
        TENANT1[Tenant A]
        TENANT2[Tenant B]
    end

    subgraph "Site Level - Tenant A"
        SITE_A1[Site A1]
        SITE_A2[Site A2]
    end

    subgraph "Site Level - Tenant B"
        SITE_B1[Site B1]
    end

    subgraph "User Context"
        USER_CTX[User Session]
        ACTIVE_TENANT[Active Tenant]
        ACTIVE_SITE[Active Site]
    end

    PLATFORM --> TENANT1
    PLATFORM --> TENANT2

    TENANT1 --> SITE_A1
    TENANT1 --> SITE_A2
    TENANT2 --> SITE_B1

    USER_CTX --> ACTIVE_TENANT
    ACTIVE_TENANT --> ACTIVE_SITE

    style PLATFORM fill:#e1f5fe
    style TENANT1 fill:#e8f5e9
    style TENANT2 fill:#e8f5e9

Key Subsystems

Tenant Isolation

Data isolation and context management. View Tenant Isolation Details

Permission System

Role-based access control architecture. View Permission System Details

Service Registry

Dependency injection and service management. View Service Registry Details

Authentication Flow

sequenceDiagram
    participant User
    participant Client
    participant Auth as Auth Service
    participant Session as Session Store
    participant DB as Database

    User->>Client: Login request
    Client->>Auth: Authenticate(email, password)
    Auth->>DB: Verify credentials
    DB-->>Auth: User record

    alt Valid credentials
        Auth->>Auth: Generate tokens
        Auth->>Session: Store session
        Auth-->>Client: Access token + Refresh token
        Client-->>User: Login success
    else Invalid credentials
        Auth-->>Client: Authentication failed
        Client-->>User: Error message
    end

    Note over User,DB: Subsequent requests

    User->>Client: API request
    Client->>Auth: Validate token
    Auth->>Session: Check session
    Session-->>Auth: Session valid
    Auth-->>Client: User context
    Client->>DB: Execute request

Request Context Flow

flowchart TD
    REQUEST[Incoming Request] --> EXTRACT[Extract Auth Token]

    EXTRACT --> VALIDATE{Token Valid?}
    VALIDATE -->|No| UNAUTHORIZED[401 Unauthorized]
    VALIDATE -->|Yes| DECODE[Decode Token]

    DECODE --> USER[Get User Info]
    USER --> TENANT[Resolve Tenant]

    TENANT --> HEADER{Tenant Header?}
    HEADER -->|Yes| USE_HEADER[Use Header Tenant]
    HEADER -->|No| DEFAULT[Default Tenant]

    USE_HEADER --> VERIFY{User in Tenant?}
    VERIFY -->|No| FORBIDDEN[403 Forbidden]
    VERIFY -->|Yes| SITE[Resolve Site]
    DEFAULT --> SITE

    SITE --> PERMISSIONS[Load Permissions]
    PERMISSIONS --> CONTEXT[Build Context]

    CONTEXT --> CTX_OBJ[Context Object]
    CTX_OBJ --> USER_ID[userId]
    CTX_OBJ --> TENANT_ID[tenantId]
    CTX_OBJ --> SITE_ID[siteId]
    CTX_OBJ --> PERMS[permissions]

    CTX_OBJ --> PROCEED[Proceed to Handler]

    style CONTEXT fill:#e8f5e9
    style UNAUTHORIZED fill:#ffebee
    style FORBIDDEN fill:#ffebee

User Roles

Role	Scope	Description
super_admin	Platform	Full platform access
tenant_owner	Tenant	Full tenant access
tenant_admin	Tenant	Tenant management
site_admin	Site	Site configuration
manager	Site	Operations management
staff	Site	Limited operations
viewer	Site	Read-only access

Context Propagation

flowchart LR
    subgraph "Request Entry"
        HEADERS[Request Headers]
        COOKIES[Cookies]
        TOKEN[Auth Token]
    end

    subgraph "Context Building"
        MIDDLEWARE[Auth Middleware]
        RESOLVER[Context Resolver]
    end

    subgraph "Context Object"
        CTX[Request Context]
        DB_CTX[Database Context]
        SVC_CTX[Service Context]
    end

    subgraph "Consumers"
        TRPC_PROC[TRPC Procedures]
        SERVICES[Domain Services]
        QUERIES[Database Queries]
    end

    HEADERS --> MIDDLEWARE
    COOKIES --> MIDDLEWARE
    TOKEN --> MIDDLEWARE

    MIDDLEWARE --> RESOLVER
    RESOLVER --> CTX

    CTX --> DB_CTX
    CTX --> SVC_CTX

    CTX --> TRPC_PROC
    SVC_CTX --> SERVICES
    DB_CTX --> QUERIES

    style CTX fill:#e8f5e9

System Configuration

flowchart TD
    subgraph "Configuration Sources"
        ENV[Environment Variables]
        DB_CONFIG[Database Config]
        FEATURE[Feature Flags]
    end

    subgraph "Configuration Layers"
        PLATFORM_CFG[Platform Config]
        TENANT_CFG[Tenant Config]
        SITE_CFG[Site Config]
    end

    subgraph "Consumers"
        APP[Application]
        SERVICES_CFG[Services]
        UI[User Interface]
    end

    ENV --> PLATFORM_CFG
    DB_CONFIG --> TENANT_CFG
    DB_CONFIG --> SITE_CFG
    FEATURE --> PLATFORM_CFG

    PLATFORM_CFG --> TENANT_CFG
    TENANT_CFG --> SITE_CFG

    SITE_CFG --> APP
    SITE_CFG --> SERVICES_CFG
    SITE_CFG --> UI

    style SITE_CFG fill:#e8f5e9

Error Handling Architecture

flowchart TD
    ERROR[Error Occurs] --> TYPE{Error Type}

    TYPE --> AUTH_ERR[Authentication Error]
    TYPE --> AUTHZ_ERR[Authorization Error]
    TYPE --> VALID_ERR[Validation Error]
    TYPE --> BIZ_ERR[Business Error]
    TYPE --> SYS_ERR[System Error]

    AUTH_ERR --> CODE_401[401 Unauthorized]
    AUTHZ_ERR --> CODE_403[403 Forbidden]
    VALID_ERR --> CODE_400[400 Bad Request]
    BIZ_ERR --> CODE_422[422 Unprocessable]
    SYS_ERR --> CODE_500[500 Internal Error]

    CODE_401 --> LOG[Log Error]
    CODE_403 --> LOG
    CODE_400 --> LOG
    CODE_422 --> LOG
    CODE_500 --> LOG

    LOG --> MONITOR{Critical?}
    MONITOR -->|Yes| ALERT[Alert Team]
    MONITOR -->|No| RECORD[Record Metric]

    CODE_401 --> RESPONSE[Error Response]
    CODE_403 --> RESPONSE
    CODE_400 --> RESPONSE
    CODE_422 --> RESPONSE
    CODE_500 --> RESPONSE

    style CODE_500 fill:#ffebee

Platform Domain

On this page