# grifthedev/thechase-v1 architecture

> Architecture diagram of the GitHub repository grifthedev/thechase-v1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grifthedev/thechase-v1
- Repository: https://github.com/grifthedev/thechase-v1

## Overview

##### Project type and purpose
- This is a full-stack SvelteKit web application that implements a real-time game (based on the abundant API routes like `advance_board`, `submit_contestant_answer`, etc.).
- The frontend is built in Svelte/SvelteKit (`src/routes/*.svelte`, `src/app.html`), styled via Tailwind/PostCSS, and served by a Node.js server managed by SvelteKit.
- The backend is embedded in SvelteKit’s server endpoints (`src/routes/api/.../+server.ts`), interacting with a data layer (Firebase, JSON files) and custom modules (`src/lib/database.ts`, `src/lib/firebase.ts`, `src/lib/server/startGame.ts`).

##### File structure to infer architectural components
- Top-level:
– Configuration: `svelte.config.js`, `vite.config.ts`, `tsconfig.json`, `postcss.config.js`, `tailwind.config.js`
– Package definitions: `package.json`, `package-lock.json`, `.npmrc`, `.gitignore`
– Static assets: `static/`
- `src/` houses both client and server code.
– Client/UI:
· `src/app.html`, `src/app.css`, `src/routes/*.svelte` (pages & layouts), `src/lib/assets/*`
– Server/API:
· `src/hooks.server.ts` (global hooks, e.g., auth/session),
· `src/routes/api/*/+server.ts` (REST-style endpoints implementing game logic),
· `src/lib/server/startGame.ts` (game-initialization logic)
– Shared modules:
· `src/lib/database.ts` (DB abstractions), `src/lib/firebase.ts` (firebase integration), `src/lib/logger.ts`, `src/lib/utils.ts`, `src/lib/stores.ts` (Svelte stores for client state)

##### Main components
a. Client Browser (UI)
- SvelteKit app pages
- Svelte stores (state management)
- Assets (images/questions JSON for client-side)
b. SvelteKit Server
- HTTP routing layer
- Hooks (auth/session initialization)
- API endpoints (game control, answer submission)
- Business logic modules (`startGame`, `utils`, `logger`)
c. Data Layer
- Firebase (Realtime Database or Firestore) via `firebase.ts`
- Local JSON files (`board.json`, `config.json`, `questions.ts` in `assets`)
d. External Integrations
- Firebase service (external)
- Potential logging/monitoring (if any external sink)
e. Build & Deployment
- Vite (bundling)
- Tailwind/PostCSS (style pipeline)

- Browser → SvelteKit server (page request / SSR)
- Browser → SvelteKit server (XHR/Fetch to `/api/*`)
- Server → Firebase (read/write game state)
- Server → Local JSON files (read initial game/board config)
- Server → Client (SSR HTML, or JSON payloads)
- Client ↔ Svelte stores (in-memory state)

##### Architectural patterns & design principles
- Monolith with clear separation: UI routes vs API routes
- Shared code approach: UI & Server share TypeScript modules (`src/lib`)
- RESTful API pattern under `/api/*`
- Server-Side Rendering combined with client hydration (in SvelteKit)
- Single-page application (SPA) behavior for dynamic game updates

##### Detail and clarity
- Related files under each component for traceability.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top-level user
    Browser["User Browser"]:::external

    %% Main application container
    subgraph "SvelteKit Application (Node.js + Vite)"
        direction TB

        subgraph "Frontend (SSR + Hydration)"
            direction TB
            Layout["+layout.svelte"]:::frontend
            Home["+page.svelte"]:::frontend
            Board["board/+page.svelte"]:::frontend
            Chaser["chaserAnswer/+page.svelte"]:::frontend
            Contestant["contestantAnswer/+page.svelte"]:::frontend
            Question["question/+page.svelte"]:::frontend
            TestPage["test/+page.svelte"]:::frontend
            Admin["admin/+page.svelte"]:::frontend
            Stores["stores.ts"]:::frontend
            Assets["questions.ts"]:::frontend
        end

        subgraph "Backend (API & Logic)"
            direction TB

            subgraph "Routing & Hooks"
                direction TB
                Hooks["hooks.server.ts"]:::server
                API_advance_board["advance_board/+server.ts"]:::server
                API_advance_game["advance_game_next_team/+server.ts"]:::server
                API_advance_chaser_final["advance_to_chaser_final/+server.ts"]:::server
                API_change_chaser_step["change_chaser_step_fc/+server.ts"]:::server
                API_change_cont_step["change_cont_step_fc/+server.ts"]:::server
                API_change_slide["change_slide_out/+server.ts"]:::server
                API_change_timer["change_timer_state/+server.ts"]:::server
                API_game_state["game_state_change/+server.ts"]:::server
                API_init_game["init_game/+server.ts"]:::server
                API_question_state["question_state_change/+server.ts"]:::server
                API_reset_round["reset_question_round/+server.ts"]:::server
                API_set_chaser["set_chaser_pos/+server.ts"]:::server
                API_set_contestant["set_contestant_pos/+server.ts"]:::server
                API_start_game["start_game/+server.ts"]:::server
                API_submit_chaser["submit_chaser_answer/+server.ts"]:::server
                API_submit_contestant["submit_contestant_answer/+server.ts"]:::server
                API_test["test/+server.ts"]:::server
            end

            subgraph "Business Logic"
                direction TB
                StartGame["startGame.ts"]:::server
                Utils["utils.ts"]:::server
                Logger["logger.ts"]:::server
            end

            subgraph "Data Access"
                direction TB
                Database["database.ts"]:::server
                FirebaseMod["firebase.ts"]:::server
            end
        end
    end

    %% Data stores
    FirebaseDB(["Firebase DB"]):::external
    LocalJSON(["Local JSON (board.json, config.json)"]):::data

    %% Build & Deployment tools
    subgraph "Build & Deployment"
        direction TB
        SvelteConfig["svelte.config.js"]:::tool
        ViteConfig["vite.config.ts"]:::tool
        Tailwind["tailwind.config.js"]:::tool
        PostCSS["postcss.config.js"]:::tool
        TSConfig["tsconfig.json"]:::tool
        Package["package.json"]:::tool
    end

    %% Connections
    Browser -->|"SSR page render / REST API"| Layout
    Browser -->|"Fetch /api/*"| API_init_game
    Layout -->|"uses"| Stores
    Layout -->|"imports"| Assets
    Hooks -->|applies| API_init_game
    API_init_game -->|"calls"| StartGame
    any -->|"reads/writes"| FirebaseMod
    FirebaseMod -->|"connects"| FirebaseDB
    Database -->|"reads"| LocalJSON
    API_init_game --> Database
    StartGame --> Database
    API_submit_contestant --> Database
    API_submit_chaser --> Database
    API_game_state --> FirebaseMod
    API_reset_round --> Database
    Business_Logic --> Data_Access

    %% Click events for file mapping
    click Layout "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/+layout.svelte"
    click Home "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/+page.svelte"
    click Board "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/board/+page.svelte"
    click Chaser "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/chaserAnswer/+page.svelte"
    click Contestant "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/contestantAnswer/+page.svelte"
    click Question "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/question/+page.svelte"
    click TestPage "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/test/+page.svelte"
    click Admin "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/admin/+page.svelte"
    click Stores "https://github.com/grifthedev/thechase-v1/blob/main/src/lib/stores.ts"
    click Assets "https://github.com/grifthedev/thechase-v1/blob/main/src/lib/assets/questions.ts"
    click Hooks "https://github.com/grifthedev/thechase-v1/blob/main/src/hooks.server.ts"
    click API_advance_board "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/advance_board/+server.ts"
    click API_advance_game "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/advance_game_next_team/+server.ts"
    click API_advance_chaser_final "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/advance_to_chaser_final/+server.ts"
    click API_change_chaser_step "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/change_chaser_step_fc/+server.ts"
    click API_change_cont_step "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/change_cont_step_fc/+server.ts"
    click API_change_slide "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/change_slide_out/+server.ts"
    click API_change_timer "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/change_timer_state/+server.ts"
    click API_game_state "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/game_state_change/+server.ts"
    click API_init_game "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/init_game/+server.ts"
    click API_question_state "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/question_state_change/+server.ts"
    click API_reset_round "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/reset_question_round/+server.ts"
    click API_set_chaser "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/set_chaser_pos/+server.ts"
    click API_set_contestant "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/set_contestant_pos/+server.ts"
    click API_start_game "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/start_game/+server.ts"
    click API_submit_chaser "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/submit_chaser_answer/+server.ts"
    click API_submit_contestant "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/submit_contestant_answer/+server.ts"
    click API_test "https://github.com/grifthedev/thechase-v1/blob/main/src/routes/api/test/+server.ts"
    click StartGame "https://github.com/grifthedev/thechase-v1/blob/main/src/lib/server/startGame.ts"
    click Utils "https://github.com/grifthedev/thechase-v1/blob/main/src/lib/utils.ts"
    click Logger "https://github.com/grifthedev/thechase-v1/blob/main/src/lib/logger.ts"
    click Database "https://github.com/grifthedev/thechase-v1/blob/main/src/lib/database.ts"
    click FirebaseMod "https://github.com/grifthedev/thechase-v1/blob/main/src/lib/firebase.ts"
    click LocalJSON "https://github.com/grifthedev/thechase-v1/blob/main/src/lib/config.json"
    click LocalJSON "https://github.com/grifthedev/thechase-v1/blob/main/src/lib/board.json"
    click SvelteConfig "https://github.com/grifthedev/thechase-v1/blob/main/svelte.config.js"
    click ViteConfig "https://github.com/grifthedev/thechase-v1/blob/main/vite.config.ts"
    click Tailwind "https://github.com/grifthedev/thechase-v1/blob/main/tailwind.config.js"
    click PostCSS "https://github.com/grifthedev/thechase-v1/blob/main/postcss.config.js"
    click TSConfig "https://github.com/grifthedev/thechase-v1/blob/main/tsconfig.json"
    click Package "https://github.com/grifthedev/thechase-v1/blob/main/package.json"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064
    classDef server fill:#E8F5E9,stroke:#1B5E20
    classDef data fill:#FFF3E0,stroke:#E65100
    classDef tool fill:#EDE7F6,stroke:#4527A0
    classDef external fill:#ECEFF1,stroke:#607D8B

    class FirebaseDB external
    class LocalJSON data
```
