# chinoarror/coup-game architecture

> Architecture diagram of the GitHub repository chinoarror/coup-game, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chinoarror/coup-game
- Repository: https://github.com/chinoarror/coup-game
- Video tour (about a minute): https://gitdiagram.com/chinoarror/coup-game/video

## Overview

Coup: Shadow Protocol is an authenticated browser game with a solo human-versus-two-AI match and separate authenticated multiplayer rooms. The principal path runs from the browser entry and login through a game view, turn/rule resolution, AI decisions where applicable, and Worker-backed persistence or room updates. Documented supporting capabilities include room invitations, realtime spectator-safe state, match history, leaderboard, and admin access-code controls. Sampled sources establish key frontend, engine, AI, and room paths; unsampled endpoints are represented only where README/tree evidence supports the subsystem, with uncertain internal wiring omitted.

Main entry points: [`worker.ts`](https://github.com/chinoarror/coup-game/blob/main/worker.ts) (API Worker), [`index.tsx`](https://github.com/chinoarror/coup-game/blob/main/index.tsx) (App entry), [`App.tsx`](https://github.com/chinoarror/coup-game/blob/main/App.tsx) (Solo match), [`roomGame.ts`](https://github.com/chinoarror/coup-game/blob/main/roomGame.ts) (Room Durable Object)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser experience"]
  node_entry["App entry<br/>[index.tsx]"]
  node_login["Login<br/>[Login.tsx]"]
  node_solo["Solo match<br/>[App.tsx]"]
  node_roomhub["Room hub<br/>[GameHub.tsx]"]
  node_roomlobby["Room lobby<br/>[RoomLobby.tsx]"]
  node_roommatch["Room match<br/>[RoomMatch.tsx]"]
  node_historyui["Match history<br/>[History.tsx]"]
  node_leaderboardui["Leaderboard<br/>[Leaderboard.tsx]"]
  node_adminui["Admin dashboard<br/>[AdminPanel.tsx]"]
  node_rulesui["Rules view<br/>[Rules.tsx]"]
end

subgraph group_gameplay["Game runtime"]
  node_engine["Game engine<br/>[gameEngine.ts]"]
  node_prompt["AI prompt<br/>[aiPrompt.ts]"]
  node_aiweb["Solo AI client<br/>[geminiService.ts]"]
  node_rules["Rules service<br/>[rules.ts]"]
end

subgraph group_backend["Worker services"]
  node_worker["API Worker<br/>[worker.ts]"]
  node_roomgame["Room Durable Object<br/>[roomGame.ts]"]
  node_roomclient["Room API client<br/>[roomClient.ts]"]
  node_rooms["Room services<br/>[rooms.ts]"]
  node_roomstate["State projection<br/>[roomState.ts]"]
  node_history["History service<br/>[history.ts]"]
  node_ai["AI gateway<br/>[aiGateway.ts]"]
end

subgraph group_integrations["External services"]
  node_d1[("Cloudflare D1<br/>[schema.sql]")]
  node_auth["Auth Center"]
  node_relay["AI relay"]
  node_models["AI providers"]
end

node_player(("Player"))

node_player -->|"opens"| node_entry
node_entry -->|"shows"| node_login
node_entry -->|"routes"| node_solo
node_entry -->|"routes"| node_roomhub
node_entry -->|"routes"| node_historyui
node_entry -->|"routes"| node_leaderboardui
node_entry -->|"routes"| node_adminui
node_entry -->|"routes"| node_rulesui
node_solo -->|"loads session"| node_worker
node_solo -->|"applies moves"| node_engine
node_solo -->|"requests decisions"| node_aiweb
node_aiweb -->|"builds request"| node_prompt
node_aiweb -->|"posts decision"| node_worker
node_roomhub -->|"calls room API"| node_roomclient
node_roomhub -->|"shows lobby"| node_roomlobby
node_roomhub -->|"shows match"| node_roommatch
node_roomclient -->|"requests routes"| node_worker
node_worker -->|"verifies session"| node_auth
node_worker -->|"reads/writes"| node_d1
node_worker -->|"validates rooms"| node_rooms
node_worker -->|"dispatches room calls"| node_roomgame
node_roomgame -->|"resolves moves"| node_engine
node_roomgame -->|"projects state"| node_roomstate
node_roomgame -->|"builds AI request"| node_prompt
node_roomgame -->|"requests channel"| node_ai
node_worker -->|"requests channel"| node_ai
node_ai -->|"sends signed request"| node_relay
node_relay -->|"forwards request"| node_models
node_solo -->|"submits match"| node_history
node_history -->|"stores records"| node_d1
node_historyui -->|"loads history"| node_worker
node_leaderboardui -->|"loads rankings"| node_worker
node_adminui -->|"manages access"| node_worker
node_rulesui -->|"renders rules"| node_rules

click node_entry "https://github.com/chinoarror/coup-game/blob/main/index.tsx"
click node_login "https://github.com/chinoarror/coup-game/blob/main/Login.tsx"
click node_solo "https://github.com/chinoarror/coup-game/blob/main/App.tsx"
click node_roomhub "https://github.com/chinoarror/coup-game/blob/main/GameHub.tsx"
click node_roomlobby "https://github.com/chinoarror/coup-game/blob/main/RoomLobby.tsx"
click node_roommatch "https://github.com/chinoarror/coup-game/blob/main/RoomMatch.tsx"
click node_historyui "https://github.com/chinoarror/coup-game/blob/main/History.tsx"
click node_leaderboardui "https://github.com/chinoarror/coup-game/blob/main/Leaderboard.tsx"
click node_adminui "https://github.com/chinoarror/coup-game/blob/main/AdminPanel.tsx"
click node_rulesui "https://github.com/chinoarror/coup-game/blob/main/Rules.tsx"
click node_engine "https://github.com/chinoarror/coup-game/blob/main/utils/gameEngine.ts"
click node_prompt "https://github.com/chinoarror/coup-game/blob/main/services/aiPrompt.ts"
click node_aiweb "https://github.com/chinoarror/coup-game/blob/main/services/geminiService.ts"
click node_worker "https://github.com/chinoarror/coup-game/blob/main/worker.ts"
click node_roomgame "https://github.com/chinoarror/coup-game/blob/main/roomGame.ts"
click node_roomclient "https://github.com/chinoarror/coup-game/blob/main/services/roomClient.ts"
click node_rooms "https://github.com/chinoarror/coup-game/blob/main/services/rooms.ts"
click node_roomstate "https://github.com/chinoarror/coup-game/blob/main/services/roomState.ts"
click node_history "https://github.com/chinoarror/coup-game/blob/main/services/history.ts"
click node_rules "https://github.com/chinoarror/coup-game/blob/main/services/rules.ts"
click node_ai "https://github.com/chinoarror/coup-game/blob/main/services/aiGateway.ts"
click node_d1 "https://github.com/chinoarror/coup-game/blob/main/schema.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_login,node_solo,node_roomhub,node_roomlobby,node_roommatch,node_historyui,node_leaderboardui,node_adminui,node_rulesui toneBlue
class node_engine,node_prompt,node_aiweb,node_rules toneAmber
class node_worker,node_roomgame,node_roomclient,node_rooms,node_roomstate,node_history,node_ai toneMint
class node_d1,node_auth,node_relay,node_models toneRose
class node_player toneIndigo
```

## Components

### Browser experience

- [App entry](https://github.com/chinoarror/coup-game/blob/main/index.tsx): `index.tsx`
- [Login](https://github.com/chinoarror/coup-game/blob/main/Login.tsx): `Login.tsx`
- [Solo match](https://github.com/chinoarror/coup-game/blob/main/App.tsx): `App.tsx`
- [Room hub](https://github.com/chinoarror/coup-game/blob/main/GameHub.tsx): `GameHub.tsx`
- [Room lobby](https://github.com/chinoarror/coup-game/blob/main/RoomLobby.tsx): `RoomLobby.tsx`
- [Room match](https://github.com/chinoarror/coup-game/blob/main/RoomMatch.tsx): `RoomMatch.tsx`
- [Match history](https://github.com/chinoarror/coup-game/blob/main/History.tsx): `History.tsx`
- [Leaderboard](https://github.com/chinoarror/coup-game/blob/main/Leaderboard.tsx): `Leaderboard.tsx`
- [Admin dashboard](https://github.com/chinoarror/coup-game/blob/main/AdminPanel.tsx): `AdminPanel.tsx`
- [Rules view](https://github.com/chinoarror/coup-game/blob/main/Rules.tsx): `Rules.tsx`

### Game runtime

- [Game engine](https://github.com/chinoarror/coup-game/blob/main/utils/gameEngine.ts): `utils/gameEngine.ts`
- [AI prompt](https://github.com/chinoarror/coup-game/blob/main/services/aiPrompt.ts): `services/aiPrompt.ts`
- [Solo AI client](https://github.com/chinoarror/coup-game/blob/main/services/geminiService.ts): `services/geminiService.ts`
- [Rules service](https://github.com/chinoarror/coup-game/blob/main/services/rules.ts): `services/rules.ts`

### Worker services

- [API Worker](https://github.com/chinoarror/coup-game/blob/main/worker.ts): `worker.ts`
- [Room Durable Object](https://github.com/chinoarror/coup-game/blob/main/roomGame.ts): `roomGame.ts`
- [Room API client](https://github.com/chinoarror/coup-game/blob/main/services/roomClient.ts): `services/roomClient.ts`
- [Room services](https://github.com/chinoarror/coup-game/blob/main/services/rooms.ts): `services/rooms.ts`
- [State projection](https://github.com/chinoarror/coup-game/blob/main/services/roomState.ts): `services/roomState.ts`
- [History service](https://github.com/chinoarror/coup-game/blob/main/services/history.ts): `services/history.ts`
- [AI gateway](https://github.com/chinoarror/coup-game/blob/main/services/aiGateway.ts): `services/aiGateway.ts`

### External services

- [Cloudflare D1](https://github.com/chinoarror/coup-game/blob/main/schema.sql): `schema.sql`
- **Auth Center**
- **AI relay**
- **AI providers**

### Other components

- **Player**

## Connections

- Player → App entry: opens
- App entry → Login: shows
- App entry → Solo match: routes
- App entry → Room hub: routes
- App entry → Match history: routes
- App entry → Leaderboard: routes
- App entry → Admin dashboard: routes
- App entry → Rules view: routes
- Solo match → API Worker: loads session
- Solo match → Game engine: applies moves
- Solo match → Solo AI client: requests decisions
- Solo AI client → AI prompt: builds request
- Solo AI client → API Worker: posts decision
- Room hub → Room API client: calls room API
- Room hub → Room lobby: shows lobby
- Room hub → Room match: shows match
- Room API client → API Worker: requests routes
- API Worker → Auth Center: verifies session
- API Worker → Cloudflare D1: reads/writes
- API Worker → Room services: validates rooms
- API Worker → Room Durable Object: dispatches room calls
- Room Durable Object → Game engine: resolves moves
- Room Durable Object → State projection: projects state
- Room Durable Object → AI prompt: builds AI request
- Room Durable Object → AI gateway: requests channel
- API Worker → AI gateway: requests channel
- AI gateway → AI relay: sends signed request
- AI relay → AI providers: forwards request
- Solo match → History service: submits match
- History service → Cloudflare D1: stores records
- Match history → API Worker: loads history
- Leaderboard → API Worker: loads rankings
- Admin dashboard → API Worker: manages access
- Rules view → Rules service: renders rules