System Architecture

graph TB
    subgraph Client["Client Layer (Browser / PWA)"]
        direction LR
        UI["React + Vite SPA"]
        SW["Service Worker\n(offline cache)"]
        WM["Web App Manifest\n(PWA install)"]
        UI --- SW
        UI --- WM
    end

    subgraph AppServer["Application Server (Node.js + Fastify)"]
        direction LR
        REST["REST API\nRoutes"]
        AUTH_MW["Auth Middleware\n(JWT verify)"]
        SCORE_SVC["scoring.service.ts\n(core engine)"]
        EMAIL_SVC["email.service.ts"]
        CRON["pg_cron / VPS cron\n(scheduled jobs)"]
        REST --> AUTH_MW
        AUTH_MW --> SCORE_SVC
        AUTH_MW --> EMAIL_SVC
        CRON --> EMAIL_SVC
    end

    subgraph Supabase["Supabase (self-hosted on VPS)"]
        direction TB
        PG["PostgreSQL 15\n+ RLS + pg_cron"]
        RT["Supabase Realtime\n(WebSocket / Postgres Changes)"]
        GOTRUE["GoTrue\n(Auth server / JWT)"]
        STORAGE["Supabase Storage\n(avatars, CSV exports)"]
        KONG["Kong API Gateway\n(internal reverse proxy)"]
        KONG --> PG
        KONG --> RT
        KONG --> GOTRUE
        KONG --> STORAGE
        RT --> PG
    end

    subgraph External["External Services"]
        SMTP["Email Provider\n(Resend / Postmark)"]
        VAPID["Web Push / VAPID\n(push notifications)"]
        GH["GitHub Actions\n(CI/CD)"]
    end

    subgraph Infra["Infrastructure (VPS — Ubuntu + Docker)"]
        CADDY["Caddy\n(reverse proxy + TLS)"]
        DOCKER["Docker Compose\n(all services)"]
    end

    Client -- "HTTPS REST" --> CADDY
    Client -- "WebSocket" --> CADDY
    CADDY --> AppServer
    CADDY --> Supabase
    AppServer --> Supabase
    AppServer --> SMTP
    AppServer --> VAPID
    VAPID -- "push" --> Client
    SMTP -- "email" --> Client
    GH -- "deploy" --> DOCKER
    DOCKER --> AppServer
    DOCKER --> Supabase

    style Client fill:#dbeafe,stroke:#3b82f6
    style AppServer fill:#dcfce7,stroke:#22c55e
    style Supabase fill:#fef9c3,stroke:#eab308
    style External fill:#fce7f3,stroke:#ec4899
    style Infra fill:#f3e8ff,stroke:#a855f7