# t3-content/quipslop architecture

> Architecture diagram of the GitHub repository t3-content/quipslop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/t3-content/quipslop
- Repository: https://github.com/t3-content/quipslop

## Overview

##### What this project is (from the tree + README)
**Quipslop** appears to be a **Bun + TypeScript web app** used live on Twitch. The file layout strongly suggests a **single-server “full-stack” app** that:
- Serves multiple **browser UIs/pages** (separate entrypoints for different roles):
- `frontend.tsx` (main viewer/user-facing UI)
- `admin.tsx` / `admin.html` (control panel for the operator/mod)
- `broadcast.ts` / `broadcast.html` (broadcast/overlay view for OBS “browser source”)
- `history.tsx` / `history.html` (past rounds/history view)
- Runs a backend in `server.ts` with domain logic in `game.ts`
- Persists state via `db.ts` (+ `check-db.ts`)
- Has deployment/build artifacts: `Dockerfile`, `bun.lock`, `tsconfig.json`, `public/assets/...`

##### Viewer / Main Web UI
- `index.html`
- `frontend.tsx`, `frontend.css`
##### Admin UI (Operator)
- `admin.html`
- `admin.tsx`, `admin.css`
##### Broadcast/Overlay UI (OBS Browser Source)
- `broadcast.html`
- `broadcast.ts`, `broadcast.css`
##### History UI
- `history.html`
- `history.tsx`, `history.css`

##### Backend container (single service)
- **Bun Server / API + Realtime Hub**
- `server.ts` (request handling, routing, probably websocket/SSE)
- Serves static assets from `/public` and compiled bundles for the pages

- **Game/Domain Engine**
- `game.ts` (state machine, scoring, round progression, etc.)
- **Persistence Layer**
- `db.ts` (DB connection + queries)
- `check-db.ts` (schema validation / migrations / sanity checks)
- **Prompt/Content Generation**
- `prompts.ts` (very likely content templates or generation logic used by the game)
- **Utilities / Tests**
- `bulk-test.ts` (load/test harness hitting APIs or simulating sessions)

##### Data store(s)
- **Database (persistent state)**
- connected via `db.ts`

##### Ops / deployment / build
- **Bun toolchain**
- `package.json`, `bun.lock`, `tsconfig.json`
- **Containerization**
- `Dockerfile`, `.dockerignore`
- **Static assets**
- `public/assets/logos/...`
- **Scripts**
- `scripts/stream-browser.ts` (likely launches/controls a browser for streaming workflows)

##### Single-service backend with modular domain separation
- `server.ts` (transport) separated from `game.ts` (domain) and `db.ts` (persistence)
##### Multiple frontends / multiple entrypoints
- Distinct pages for distinct roles (viewer/admin/broadcast/history)
##### Realtime system
- Presence of a dedicated broadcast UI strongly implies push-based updates
##### Stream-operator workflow integration
- Dedicated script under `scripts/` implies tooling around running the show live

Call these out using labels like “Transport Layer”, “Domain Layer”, “Persistence”, “Realtime”.

##### Level 1 — System Context (who uses it)
- Viewer(s)
- Stream Operator (Admin)
- OBS / Broadcast overlay (Browser Source)

- “Plays/Views”
- “Controls game”
- “Renders overlay”
- “Reads/Writes state”

- **Bun Server Container** (Docker)
- **Database**
- **Viewer Web App**
- **Admin Web App**
- **Broadcast Web App**
- **History Web App**

- HTTP for page load
- Realtime channel for updates
- DB connections

- `server.ts` (HTTP routes + realtime hub)
- `game.ts` (game engine)
- `prompts.ts` (content)
- `db.ts` (persistence adapter)
- `check-db.ts` (ops/migrations check)
Optionally show:
- `bulk-test.ts` (test client)
- `scripts/stream-browser.ts` (operator tool)

##### Labels
- Use **actual filenames** for component names when possible (e.g., “Game Engine (`game.ts`)”).
- “HTTP GET (static/bundle)”
- “HTTP API (admin commands)”
- “WebSocket/SSE (state updates)”
- “SQL queries (state persistence)”

##### Detail bias (important for this repo)
Because the README doesn’t explain architecture, your best accuracy comes from **maximizing explicit components** derived from the tree:
- Keep **Admin vs Broadcast vs Viewer vs History** separate.
- Keep **server transport vs game domain vs DB** separate.
- **scripts and test harnesses** as “supporting components” (a separate lane).

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% Level 1 — System Context
  %% =========================================================
  subgraph "Level 1 — System Context"
    direction TB

    Viewers["Viewer(s)\nBrowser Clients"]:::person
    Operator["Stream Operator / Mod\n(Admin Browser)"]:::person
    OBS["OBS Browser Source\n(Broadcast Overlay)"]:::person
    HistUser["History Viewer\n(Browser)"]:::person

    System["Quipslop System\n(Bun + TypeScript)"]:::system
    DB[("Database\n(persistent state)")]:::datastore

    Viewers -->|"plays/views"| System
    Operator -->|"controls_game"| System
    OBS -->|"renders_overlay"| System
    HistUser -->|"views_history"| System

    System -->|"reads/writes_state"| DB
  end

  %% =========================================================
  %% Level 2 — Container Diagram
  %% =========================================================
  subgraph "Level 2 — Containers (Runtime)"
    direction TB

    subgraph "Clients (Browsers)"
      direction TB

      subgraph "Viewer Web App"
        direction TB
        VIndex["index.html\n(Entry Point)"]:::page
        VApp["frontend.tsx\n(Client App)"]:::client
        VCss["frontend.css\n(Styles)"]:::css
        VIndex --> VApp
        VApp --> VCss
      end

      subgraph "Admin Web App (Operator)"
        direction TB
        AIndex["admin.html\n(Entry Point)"]:::page
        AApp["admin.tsx\n(Client App)"]:::client
        ACss["admin.css\n(Styles)"]:::css
        AIndex --> AApp
        AApp --> ACss
      end

      subgraph "Broadcast / Overlay Web App (OBS)"
        direction TB
        BIndex["broadcast.html\n(Entry Point)"]:::page
        BApp["broadcast.ts\n(Client App)"]:::client
        BCss["broadcast.css\n(Styles)"]:::css
        BIndex --> BApp
        BApp --> BCss
      end

      subgraph "History Web App"
        direction TB
        HIndex["history.html\n(Entry Point)"]:::page
        HApp["history.tsx\n(Client App)"]:::client
        HCss["history.css\n(Styles)"]:::css
        HIndex --> HApp
        HApp --> HCss
      end
    end

    subgraph "Backend (Single Service)"
      direction TB
      Server["Bun Server Container\n(API + Realtime Hub)"]:::server
      Static["Static File Server\n(public/ + bundles)"]:::serverLite
    end

    VIndex -->|"HTTP_GET(static+bundle)"| Static
    AIndex -->|"HTTP_GET(static+bundle)"| Static
    BIndex -->|"HTTP_GET(static+bundle)"| Static
    HIndex -->|"HTTP_GET(static+bundle)"| Static

    AApp -->|"HTTP_API(admin_commands)"| Server
    HApp -->|"HTTP_API(history_fetch)"| Server

    Server -->|"Realtime_channel(state_updates)"| VApp
    Server -->|"Realtime_channel(state_updates)"| BApp

    Static -->|"served_by"| Server

    DB2[("Database\n(persistent state)")]:::datastore
    Server -->|"DB_connection(queries)"| DB2
  end

  %% =========================================================
  %% Level 3 — Component Diagram (File-mapped)
  %% =========================================================
  subgraph "Level 3 — Components (Map to repo files)"
    direction TB

    subgraph "Bun Server / API + Realtime Hub"
      direction TB
      Srv["server.ts\n(HTTP routes + Realtime hub)"]:::server
      Game["game.ts\n(Game/Domain engine)"]:::component
      Prompts["prompts.ts\n(Prompt/content generation)"]:::component
      DBAdapter["db.ts\n(Persistence adapter)"]:::component
      DBCheck["check-db.ts\n(Schema check / migrations)"]:::ops
    end

    DB3[("Database")]:::datastore

    Srv -->|"calls(state_transitions)"| Game
    Game -->|"selects/generates"| Prompts
    Srv -->|"reads/writes"| DBAdapter
    DBAdapter -->|"SQL_queries"| DB3
    DBCheck -->|"validate/migrate"| DB3

    subgraph "Supporting Tools"
      direction TB
      Bulk["bulk-test.ts\n(Test harness)"]:::ops
      StreamScript["scripts/stream-browser.ts\n(Stream operator tooling)"]:::ops
      ToolBrowser["Launched Browser Instance"]:::external
    end

    Bulk -->|"synthetic_traffic"| Srv
    StreamScript -->|"launches"| ToolBrowser
    ToolBrowser -->|"opens(Admin/Broadcast URLs)"| AIndex
    ToolBrowser -->|"opens(Admin/Broadcast URLs)"| BIndex

    subgraph "Static Assets"
      direction TB
      PublicDir["public/\n(Static assets)"]:::asset
      LogosDir["public/assets/logos/\n(Logos)"]:::asset
      LogosDir -->|"contained_in"| PublicDir
    end

    Srv -->|"serves_static"| PublicDir
  end

  %% =========================================================
  %% Build & Deploy
  %% =========================================================
  subgraph "Build & Deploy (Ops)"
    direction TB

    Pkg["package.json\n(Bun toolchain/manifest)"]:::build
    Lock["bun.lock\n(Lockfile)"]:::build
    TS["tsconfig.json\n(TypeScript config)"]:::build
    Docker["Dockerfile\n(Containerization)"]:::build
    DIgnore[".dockerignore\n(Docker ignore rules)"]:::build

    BuildStep["Build (Bun)\ntranspile/bundle"]:::buildStep
    Image["Container Image"]:::buildStep
    Run["Run Container\n(Bun server process)"]:::buildStep

    Pkg --> BuildStep
    Lock --> BuildStep
    TS --> BuildStep
    BuildStep --> Image
    Docker --> Image
    DIgnore --> Image
    Image --> Run
    Run --> Srv
    PublicDir -->|"included/served"| Run
  end

  %% =========================================================
  %% Click events (from component_mapping)
  %% =========================================================
  click VIndex "https://github.com/t3-content/quipslop/blob/main/index.html"
  click VApp "https://github.com/t3-content/quipslop/blob/main/frontend.tsx"
  click VCss "https://github.com/t3-content/quipslop/blob/main/frontend.css"

  click AIndex "https://github.com/t3-content/quipslop/blob/main/admin.html"
  click AApp "https://github.com/t3-content/quipslop/blob/main/admin.tsx"
  click ACss "https://github.com/t3-content/quipslop/blob/main/admin.css"

  click BIndex "https://github.com/t3-content/quipslop/blob/main/broadcast.html"
  click BApp "https://github.com/t3-content/quipslop/blob/main/broadcast.ts"
  click BCss "https://github.com/t3-content/quipslop/blob/main/broadcast.css"

  click HIndex "https://github.com/t3-content/quipslop/blob/main/history.html"
  click HApp "https://github.com/t3-content/quipslop/blob/main/history.tsx"
  click HCss "https://github.com/t3-content/quipslop/blob/main/history.css"

  click Srv "https://github.com/t3-content/quipslop/blob/main/server.ts"
  click Game "https://github.com/t3-content/quipslop/blob/main/game.ts"
  click Prompts "https://github.com/t3-content/quipslop/blob/main/prompts.ts"
  click DBAdapter "https://github.com/t3-content/quipslop/blob/main/db.ts"
  click DBCheck "https://github.com/t3-content/quipslop/blob/main/check-db.ts"

  click Bulk "https://github.com/t3-content/quipslop/blob/main/bulk-test.ts"
  click StreamScript "https://github.com/t3-content/quipslop/blob/main/scripts/stream-browser.ts"

  click PublicDir "https://github.com/t3-content/quipslop/tree/main/public/"
  click LogosDir "https://github.com/t3-content/quipslop/tree/main/public/assets/logos/"

  click Pkg "https://github.com/t3-content/quipslop/blob/main/package.json"
  click Lock "https://github.com/t3-content/quipslop/blob/main/bun.lock"
  click TS "https://github.com/t3-content/quipslop/blob/main/tsconfig.json"
  click Docker "https://github.com/t3-content/quipslop/tree/main/Dockerfile"
  click DIgnore "https://github.com/t3-content/quipslop/blob/main/.dockerignore"

  %% =========================================================
  %% Styles
  %% =========================================================
  classDef person fill:#E6F0FF,stroke:#2B6CB0,stroke-width:1px,color:#0B2E4A
  classDef system fill:#E9FFF2,stroke:#2F855A,stroke-width:1px,color:#0B3D22
  classDef external fill:#F2F2F2,stroke:#666,stroke-width:1px,color:#222

  classDef client fill:#DCEBFF,stroke:#2B6CB0,stroke-width:1px,color:#0B2E4A
  classDef page fill:#CFE3FF,stroke:#2B6CB0,stroke-width:1px,color:#0B2E4A
  classDef css fill:#EAF3FF,stroke:#2B6CB0,stroke-width:1px,color:#0B2E4A

  classDef server fill:#DFF7E7,stroke:#2F855A,stroke-width:1px,color:#0B3D22
  classDef serverLite fill:#F0FFF6,stroke:#2F855A,stroke-width:1px,color:#0B3D22
  classDef component fill:#E9FFF2,stroke:#2F855A,stroke-width:1px,color:#0B3D22

  classDef datastore fill:#FFE8CC,stroke:#C05621,stroke-width:1px,color:#4A2508

  classDef ops fill:#EFEFEF,stroke:#555,stroke-width:1px,color:#222
  classDef asset fill:#FFF4E5,stroke:#C05621,stroke-width:1px,color:#4A2508

  classDef build fill:#EDE7FF,stroke:#5A3FC0,stroke-width:1px,color:#22124D
  classDef buildStep fill:#F4F0FF,stroke:#5A3FC0,stroke-width:1px,color:#22124D
```
