# central-co/triagen-web architecture

> Architecture diagram of the GitHub repository central-co/triagen-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/central-co/triagen-web
- Repository: https://github.com/central-co/triagen-web

## Overview

##### Project type and purpose
- This is a single-page web application built with Vite + React + TypeScript.
- It serves as a candidate interviewing dashboard (“triagen-web”) that:
- Uses Supabase for authentication, database, migrations, and an Edge Function for central config.
- Calls an external API (via the API_URL variable) to start interviews.
- Connects to LiveKit over WebSocket for real-time audio/video in interview rooms.

##### File structure
- Top-level files:
- package.json, tsconfig.*, vite.config.ts — build/tooling
- netlify.toml — deployment target
- .env.example — local supabase + optional API/LIVEKIT/RECAPTCHA fallbacks
- src/ directory:
- src/main.tsx + src/index.css — app entrypoint
- src/App.tsx — root layout & routing
- src/components/… — React page & UI components (LandingPage, LoginPage, Dashboard pages, InterviewRoom, etc.)
- src/hooks/… — custom hooks for auth, config loading, dashboard stats, dark mode, audio levels
- src/api/interview/start.ts — client call to your interview-start endpoint
- src/integrations/supabase — Supabase client + type definitions
- src/utils — cross-cutting utilities (apiSecurity, config)
- supabase/ directory:
- config.toml + migrations/*.sql — database schema & migrations for your Postgres instance

##### Key architectural insights from README
- Hybrid config: first load from your “get-app-config” Edge Function on Supabase, fallback to local .env in dev.
- No server-side code in this repo beyond API calls: the actual interview logic lives in a separate API server (API_URL).
- Real-time comms: LiveKit for websockets (LIVEKIT_URL).

##### Main components
a. Frontend SPA (Browser)
- React/Vite bundle deployed on Netlify (index.html + JS/CSS).
- Core UI: Login, Landing, Dashboard, InterviewRoom, NotFound.
- hooks & utils for state/config.
b. Supabase Services (Cloud)
- Auth service (sign-in, tokens).
- Postgres Database (candidates, jobs, reports…).
- Edge Function “get-app-config” (dynamic config endpoint).
- Migrations (managed separately via supabase migrations folder).
c. External Interview API
- Exposed at API_URL, used by src/api/interview/start.ts to initiate interview sessions.
d. LiveKit Real-Time Server
- WebSocket endpoint at LIVEKIT_URL for audio/video sessions.
e. Optional reCAPTCHA service (if enabled).

##### Relationships & data flows
1) Browser loads the SPA from Netlify.
2) On startup:
- SPA calls Supabase Edge Function (get-app-config) → returns API_URL, LIVEKIT_URL, RECAPTCHA_KEY.
- Falls back to VITE_* env vars if Edge Function is unreachable (development only).
3) User logs in via Supabase Auth (browser ↔ Supabase Auth API).
4) After auth:
- Browser queries Supabase Postgres for dashboard data (jobs, candidates, reports) through the Supabase client.
5) When user starts an interview:
- Browser calls API_URL/interview/start → external Interview API.
- Browser connects to LiveKit at LIVEKIT_URL via WebSocket for real-time media.
6) Real-time events flow over LiveKit; post-interview results can be written back to Supabase DB via the Supabase client or external API.

##### Architectural patterns & design principles
- Single-Page Application (SPA) with clear separation:
- Presentation (React components under src/components).
- State & side-effects (custom hooks under src/hooks).
- Integration layer (src/integrations & src/api).
- Utilities/config (src/utils).
- Hybrid configuration loading (Edge Function first, fallback env).
- Service-oriented: offload identity (Supabase Auth), storage (Supabase DB), real-time (LiveKit), business logic (external API).

##### Final checklist
- [ ] Clear component labels and grouping.
- Frontend (blue rectangles)
- Backend services (yellow clouds)
- External services (orange clouds)
- [ ] Notes on dynamic config loading order (Edge Function → env).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend SPA
    subgraph "Frontend SPA (Netlify-hosted Vite+React)" 
        style Frontend fill:#e0f3ff,stroke:#037ffc,stroke-width:2px
        A1["index.html"]:::frontend
        A2["src/main.tsx"]:::frontend
        A3["src/App.tsx"]:::frontend
        A4["src/index.css"]:::frontend
    end

    %% Integration Layer
    subgraph "Integration Layer" 
        style Integration fill:#f0f4c3,stroke:#827717,stroke-width:2px
        B1["Supabase Client"]:::integration
        B2["External Interview API Caller"]:::integration
    end

    %% Utilities & Config
    subgraph "Utilities & Config" 
        style Utils fill:#fff9c4,stroke:#f9a825,stroke-width:2px
        C1["src/utils/config.ts"]:::util
        C2["src/utils/apiSecurity.ts"]:::util
    end

    %% Supabase Services
    subgraph "Supabase Services (Cloud)" 
        style Supabase fill:#d1c4e9,stroke:#5e35b1,stroke-width:2px
        D1["Auth Service"]:::service
        D2["Postgres DB"]:::db
        D3["Edge Function: get-app-config"]:::function
        D4["Migrations"]:::db
    end

    %% External Services
    subgraph "External Services" 
        style External fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px
        E1["External Interview API @ API_URL"]:::external
        E2["LiveKit WS @ LIVEKIT_URL"]:::external
    end

    %% Data Flows
    A1 -->|"HTTP/HTTPS"| D3
    A2 -->|"HTTP/HTTPS"| D3
    A3 -->|"HTTP/HTTPS"| D3
    A4 -->|"HTTP/HTTPS"| D3

    A1 -->|"Login↔"| D1
    A2 -->|"Login↔"| D1
    A3 -->|"Login↔"| D1
    A4 -->|"Login↔"| D1

    A1 -->|"Query↔"| D2
    A2 -->|"Query↔"| D2
    A3 -->|"Query↔"| D2
    A4 -->|"Query↔"| D2

    B2 -->|"HTTP/HTTPS"| E1
    A2 -->|"uses B2"| B2
    B1 -->|"Client↔"| D1
    B1 -->|"Client↔"| D2

    A3 -->|"WebSocket"| E2

    C1 -->|"Provides config to"| A2
    C2 -->|"Security helpers for"| B2

    D3 -->|"Reads config for"| A2
    D4 -->|"Schema migrations for"| D2

    %% Click Events
    click A1 "https://github.com/central-co/triagen-web/blob/main/.vuepress/public/index.html"
    click A2 "https://github.com/central-co/triagen-web/blob/main/src/main.tsx"
    click A3 "https://github.com/central-co/triagen-web/blob/main/src/App.tsx"
    click A4 "https://github.com/central-co/triagen-web/blob/main/src/index.css"
    click B1 "https://github.com/central-co/triagen-web/blob/main/src/integrations/supabase/client.ts"
    click B2 "https://github.com/central-co/triagen-web/blob/main/src/api/interview/start.ts"
    click C1 "https://github.com/central-co/triagen-web/blob/main/src/utils/config.ts"
    click C2 "https://github.com/central-co/triagen-web/blob/main/src/utils/apiSecurity.ts"
    click D3 "https://github.com/central-co/triagen-web/blob/main/supabase/config.toml"
    click D4 "https://github.com/central-co/triagen-web/blob/main/supabase/migrations/*.sql"

    %% Styles
    classDef frontend fill:#e0f3ff,stroke:#037ffc;
    classDef integration fill:#f0f4c3,stroke:#827717;
    classDef util fill:#fff9c4,stroke:#f9a825;
    classDef service fill:#d1c4e9,stroke:#5e35b1;
    classDef db fill:#c8e6c9,stroke:#2e7d32;
    classDef function fill:#d1c4e9,stroke-dasharray: 5 5,stroke:#5e35b1;
    classDef external fill:#ffe0b2,stroke:#ef6c00;
```
