XPrivate Education — Architecture

flowchart TD
    Web["@apps/web\nTanStack Start + Hono"] --> Auth["@packages/auth\nRBAC + WhoAmI"]
    Web --> Service["@packages/service\nBusiness Logic + Zod"]
    Web --> DB["@packages/db\nDrizzle Schema"]
    Cron["@apps/cron-*\nCF Cron Workers"] --> Service
    Cron --> DB
    Auth --> DB
    Service --> DB
    DB --> Neon[("Neon Postgres 18\nvia CF Hyperdrive")]
    style Web fill:#1e3a8a,stroke:#38bdf8,color:#e2e8f0
    style Cron fill:#1e3a8a,stroke:#60a5fa,color:#e2e8f0
    style Auth fill:#4c1d95,stroke:#a78bfa,color:#e2e8f0
    style Service fill:#064e3b,stroke:#34d399,color:#e2e8f0
    style DB fill:#134e4a,stroke:#2dd4bf,color:#e2e8f0
    style Neon fill:#14532d,stroke:#4ade80,color:#e2e8f0
        

flowchart LR
    Browser(["Browser / Mobile\nCapacitor"]) -->|HTTP| Nitro["Nitro\nCF Workers"]
    Nitro -->|"/ · /dashboard/*\n/login · etc."| TSR["TanStack Start\nSSR Router"]
    Nitro -->|"/__server/*"| SF["createServerFn\nSSR data only"]
    Nitro -->|"/api/*"| Hono["Hono App\n@hono/zod-openapi"]
    Hono --> WhoAmI["/api/v1/whoami"]
    Hono --> Domain["/api/v1/..."]
    Hono --> Docs["/api/docs\nSwagger UI"]
    Hono --> Spec["/api/openapi.json\nOpenAPI 3.x"]
    TSR --> PA["@packages/auth"]
    SF --> PS["@packages/service"]
    Domain --> PA2["@packages/auth\npermission check"]
    Domain --> PS2["@packages/service"]
    style Nitro fill:#1e3a8a,stroke:#38bdf8,color:#e2e8f0
    style Hono fill:#7c2d12,stroke:#fb923c,color:#e2e8f0
    style TSR fill:#1e3a8a,stroke:#93c5fd,color:#e2e8f0
    style SF fill:#1e293b,stroke:#64748b,color:#94a3b8
        

sequenceDiagram
    actor User
    participant FE as Frontend (TanStack Start)
    participant API as Worker API (Hono)
    participant BA as Better Auth
    participant DB as Neon Postgres

    User->>FE: Visit protected route
    FE->>API: GET /api/v1/whoami
    API->>BA: Validate session cookie
    BA->>DB: Lookup session
    DB-->>BA: Not found / expired
    BA-->>API: 401 Unauthorized
    API-->>FE: 401
    FE->>FE: Redirect to /login (zero UI flash)

    User->>FE: Click Login with Google
    FE->>BA: Initiate Google OAuth
    BA-->>User: Redirect to Google consent screen
    User-->>BA: Grant consent
    BA->>DB: Upsert user + create session
    BA-->>FE: Set session cookie + redirect to /dashboard

    FE->>API: GET /api/v1/whoami
    API->>BA: Validate session cookie
    BA->>DB: Fetch user + roles
    DB->>DB: Resolve permissions (union + dedupe + negation)
    DB-->>BA: User + resolved permissions
    BA-->>API: User context
    API-->>FE: 200 { user_id, name, permissions, superuser }
    FE->>FE: Cache WhoAmI in app memory
    FE->>FE: Render dashboard (permission-gated UI)
        

sequenceDiagram
    actor Admin
    participant API as Worker API
    participant BA as Better Auth
    participant DB as Neon Postgres
    participant Mail as Email Service
    actor Invitee as Student or Tutor

    Admin->>API: POST /api/v1/users/invite {email, role}
    API->>API: requirePermission('user:invite')
    API->>BA: Create invite token for email
    BA->>DB: INSERT invite {email, role, token, expires_at, status=PENDING}
    BA->>Mail: Send invite + welcome email (activation link)
    Mail-->>Invitee: Invite email with link
    API-->>Admin: 200 {invite_id}

    Invitee->>API: GET /invite?token=xxx
    API->>BA: Validate token (not expired, not used)
    BA->>DB: CREATE user record + assign initial role
    BA->>DB: UPDATE invite status=ACCEPTED
    BA-->>Invitee: Redirect to complete profile / set password
        

flowchart TD
    A(["Incoming API Request"]) --> B["Extract session cookie"]
    B --> C{"Valid session?"}
    C -->|No| D[/"Return 401 Unauthorized"/]
    C -->|Yes| E["Fetch user from DB"]
    E --> F{"superuser = true?"}
    F -->|Yes| G[/"Pass — full access granted\n(no permission checks)"/]
    F -->|No| H["Fetch user_roles"]
    H --> I["For each role:\nfetch role_permissions"]
    I --> J["Union all permission keys\nfrom all roles"]
    J --> K["Dedupe permission set"]
    K --> L["Identify negation entries\n!permission:name format"]
    L --> M["Remove matching positive permission"]
    M --> N["Remove negation entry itself"]
    N --> O["Resolved permissions map\n{ 'student:read': true, ... }"]
    O --> P{"Route requirePermission(x)?"}
    P -->|"resolved[x] === true"| Q[/"next() — authorized"/]
    P -->|"missing or superuser bypassed"| R[/"Return 403 Forbidden"/]
    style D fill:#7f1d1d,stroke:#f87171,color:#fecaca
    style R fill:#7f1d1d,stroke:#f87171,color:#fecaca
    style G fill:#14532d,stroke:#4ade80,color:#dcfce7
    style Q fill:#14532d,stroke:#4ade80,color:#dcfce7
        

flowchart LR
    Prod[("Production\nNeon Branch")] -->|"instant branch\ncopy-on-write"| Test[("Test\nNeon Branch")]
    Test --> Migrate["Apply migrations\nDrizzle Kit"]
    Migrate --> Run["Run Vitest\nintegration tests"]
    Run --> Delete["Delete branch\n(cleanup)"]
    style Prod fill:#14532d,stroke:#4ade80,color:#dcfce7
    style Test fill:#1e3a8a,stroke:#38bdf8,color:#dbeafe
    style Delete fill:#7f1d1d,stroke:#f87171,color:#fecaca
        

sequenceDiagram
    participant C as Client (Browser/Mobile)
    participant W as Worker API
    participant R as Cloudflare R2
    participant DB as Neon Postgres

    C->>W: POST /api/v1/upload-url {filename, content_type, context}
    W->>W: Validate auth + requirePermission('document:upload')
    W->>R: Generate presigned PUT URL (S3 API, expires 15m)
    W->>DB: INSERT document_upload {status=PENDING, ...}
    W-->>C: { upload_url, upload_id, expires_in: 900 }
    Note over C,R: Worker NOT in file transfer path — no bandwidth cost
    C->>R: PUT presigned-url (direct upload, binary)
    R-->>C: 200 OK
    C->>W: POST /api/v1/upload-confirm {upload_id, success: true}
    W->>DB: UPDATE document_upload {status=UPLOADED, size_bytes, ...}
    W-->>C: { document_id }