# eitaar/driichi architecture

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

- Interactive diagram: https://gitdiagram.com/eitaar/driichi
- Repository: https://github.com/eitaar/driichi

## Overview

This is a multiplayer mahjong application: players enter rooms and play through a projected game view, while administrators manage rooms, replays, and benchmarks. The Rust workspace separates game rules and room state from server, replay, and protocol-facing crates; the frontend renders gameplay and administrative workflows. The excerpts establish several frontend and replay-module relationships, but do not show most server routing or core runtime calls, so those connections are omitted or marked unverified.

Main entry points: [`frontend/src/app.tsx`](https://github.com/eitaar/driichi/blob/main/frontend/src/app.tsx) (Web app routes), [`frontend/src/game/gameplay.tsx`](https://github.com/eitaar/driichi/blob/main/frontend/src/game/gameplay.tsx) (Gameplay view), [`frontend/src/game/three-table.tsx`](https://github.com/eitaar/driichi/blob/main/frontend/src/game/three-table.tsx) (3D table renderer), [`crates/double_riichi_core/src/room.rs`](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/room.rs) (Room runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_game["Game runtime"]
  node_core_domain["Game domain<br/>[domain.rs]"]
  node_engine["Game engine<br/>[engine.rs]"]
  node_decisions["Legal decisions<br/>[decision.rs]"]
  node_match_machine["Match progression<br/>[match_machine.rs]"]
  node_projection["State projection<br/>[projection.rs]"]
end

subgraph group_server["Server and rooms"]
  node_room["Room runtime<br/>[room.rs]"]
  node_http["HTTP service<br/>[http.rs]"]
  node_auth["Authentication<br/>[auth.rs]"]
  node_storage[("SQLite storage<br/>[storage.rs]")]
  node_oauth["OAuth integration<br/>[oauth.rs]"]
end

subgraph group_replays["Replay system"]
  node_mjson["MJSON codec<br/>[mjson.rs]"]
  node_frames["Replay frames<br/>[frames.rs]"]
  node_persistence["Replay persistence<br/>[persistence.rs]"]
end

subgraph group_frontend["Player and admin UI"]
  node_app["Web app routes<br/>[app.tsx]"]
  node_api["Frontend API<br/>[api.ts]"]
  node_gameplay["Gameplay view<br/>[gameplay.tsx]"]
  node_game_store["Game state store<br/>[store.ts]"]
  node_table["3D table renderer<br/>[three-table.tsx]"]
  node_scene["Table scene"]
  node_layout["Scene layout"]
  node_geometry["Table geometry<br/>[table-geometry.ts]"]
  node_replay_ui["Replay workspace<br/>[replay.tsx]"]
end

subgraph group_protocols["External interfaces"]
  node_mjai["MJAI adapter<br/>[lib.rs]"]
  node_mcp["MCP interface<br/>[lib.rs]"]
  node_chatgpt["ChatGPT gateway<br/>[chatgpt_gateway.rs]"]
end

node_players(("Players"))
node_admin(("Administrators"))

node_players -->|"use"| node_app
node_admin -->|"use"| node_app
node_app -->|"renders"| node_gameplay
node_app -->|"routes to"| node_replay_ui
node_app -.->|"uses"| node_api
node_gameplay -->|"renders"| node_table
node_gameplay -->|"uses"| node_game_store
node_table -->|"renders"| node_scene
node_table -->|"builds layout"| node_layout
node_scene -->|"uses"| node_layout
node_layout -->|"uses"| node_geometry
node_replay_ui -->|"requests replay data"| node_api
node_match_machine -->|"uses types"| node_core_domain
node_room -.->|"advances matches"| node_match_machine
node_room -.->|"projects state"| node_projection
node_engine -.->|"computes actions"| node_decisions
node_http -.->|"dispatches room actions"| node_room
node_http -.->|"persists records"| node_storage
node_auth -->|"reads and writes"| node_storage
node_frames -->|"uses codec"| node_mjson
node_persistence -->|"encodes events"| node_mjson
node_mjai -.->|"adapts game"| node_engine
node_mcp -.->|"exposes tools"| node_http
node_chatgpt -.->|"connects tools"| node_mcp
node_oauth -.->|"supports sign-in"| node_auth

click node_app "https://github.com/eitaar/driichi/blob/main/frontend/src/app.tsx"
click node_api "https://github.com/eitaar/driichi/blob/main/frontend/src/api.ts"
click node_gameplay "https://github.com/eitaar/driichi/blob/main/frontend/src/game/gameplay.tsx"
click node_game_store "https://github.com/eitaar/driichi/blob/main/frontend/src/game/store.ts"
click node_table "https://github.com/eitaar/driichi/blob/main/frontend/src/game/three-table.tsx"
click node_scene "https://github.com/eitaar/driichi/blob/main/frontend/src/game/three-table-scene.tsx"
click node_layout "https://github.com/eitaar/driichi/blob/main/frontend/src/game/three-table-layout.ts"
click node_geometry "https://github.com/eitaar/driichi/blob/main/frontend/src/game/table-geometry.ts"
click node_replay_ui "https://github.com/eitaar/driichi/blob/main/frontend/src/replay.tsx"
click node_core_domain "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/domain.rs"
click node_engine "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/engine.rs"
click node_decisions "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/decision.rs"
click node_match_machine "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/match_machine.rs"
click node_projection "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/projection.rs"
click node_room "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/room.rs"
click node_http "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_server/src/http.rs"
click node_auth "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_server/src/auth.rs"
click node_storage "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_server/src/storage.rs"
click node_oauth "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_server/src/oauth.rs"
click node_mjson "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_replay/src/mjson.rs"
click node_frames "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_replay/src/frames.rs"
click node_persistence "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_replay/src/persistence.rs"
click node_mjai "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_mjai/src/lib.rs"
click node_mcp "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_mcp/src/lib.rs"
click node_chatgpt "https://github.com/eitaar/driichi/blob/main/crates/double_riichi_server/src/chatgpt_gateway.rs"

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_core_domain,node_engine,node_decisions,node_match_machine,node_projection toneBlue
class node_room,node_http,node_auth,node_storage,node_oauth toneAmber
class node_mjson,node_frames,node_persistence toneMint
class node_app,node_api,node_gameplay,node_game_store,node_table,node_scene,node_layout,node_geometry,node_replay_ui toneRose
class node_mjai,node_mcp,node_chatgpt,node_players,node_admin toneIndigo
```

## Components

### Game runtime

- [Game domain](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/domain.rs): `crates/double_riichi_core/src/domain.rs`
- [Game engine](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/engine.rs): `crates/double_riichi_core/src/engine.rs`
- [Legal decisions](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/decision.rs): `crates/double_riichi_core/src/decision.rs`
- [Match progression](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/match_machine.rs): `crates/double_riichi_core/src/match_machine.rs`
- [State projection](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/projection.rs): `crates/double_riichi_core/src/projection.rs`

### Server and rooms

- [Room runtime](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_core/src/room.rs): `crates/double_riichi_core/src/room.rs`
- [HTTP service](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_server/src/http.rs): `crates/double_riichi_server/src/http.rs`
- [Authentication](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_server/src/auth.rs): `crates/double_riichi_server/src/auth.rs`
- [SQLite storage](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_server/src/storage.rs): `crates/double_riichi_server/src/storage.rs`
- [OAuth integration](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_server/src/oauth.rs): `crates/double_riichi_server/src/oauth.rs`

### Replay system

- [MJSON codec](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_replay/src/mjson.rs): `crates/double_riichi_replay/src/mjson.rs`
- [Replay frames](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_replay/src/frames.rs): `crates/double_riichi_replay/src/frames.rs`
- [Replay persistence](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_replay/src/persistence.rs): `crates/double_riichi_replay/src/persistence.rs`

### Player and admin UI

- [Web app routes](https://github.com/eitaar/driichi/blob/main/frontend/src/app.tsx): `frontend/src/app.tsx`
- [Frontend API](https://github.com/eitaar/driichi/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Gameplay view](https://github.com/eitaar/driichi/blob/main/frontend/src/game/gameplay.tsx): `frontend/src/game/gameplay.tsx`
- [Game state store](https://github.com/eitaar/driichi/blob/main/frontend/src/game/store.ts): `frontend/src/game/store.ts`
- [3D table renderer](https://github.com/eitaar/driichi/blob/main/frontend/src/game/three-table.tsx): `frontend/src/game/three-table.tsx`
- [Table scene](https://github.com/eitaar/driichi/blob/main/frontend/src/game/three-table-scene.tsx): `frontend/src/game/three-table-scene.tsx`
- [Scene layout](https://github.com/eitaar/driichi/blob/main/frontend/src/game/three-table-layout.ts): `frontend/src/game/three-table-layout.ts`
- [Table geometry](https://github.com/eitaar/driichi/blob/main/frontend/src/game/table-geometry.ts): `frontend/src/game/table-geometry.ts`
- [Replay workspace](https://github.com/eitaar/driichi/blob/main/frontend/src/replay.tsx): `frontend/src/replay.tsx`

### External interfaces

- [MJAI adapter](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_mjai/src/lib.rs): `crates/double_riichi_mjai/src/lib.rs`
- [MCP interface](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_mcp/src/lib.rs): `crates/double_riichi_mcp/src/lib.rs`
- [ChatGPT gateway](https://github.com/eitaar/driichi/blob/main/crates/double_riichi_server/src/chatgpt_gateway.rs): `crates/double_riichi_server/src/chatgpt_gateway.rs`

### Other components

- **Players**
- **Administrators**

## Connections

- Players → Web app routes: use
- Administrators → Web app routes: use
- Web app routes → Gameplay view: renders (evidence: `frontend/src/app.tsx`)
- Web app routes → Replay workspace: routes to (evidence: `frontend/src/app.tsx`)
- Web app routes → Frontend API: uses (evidence: `frontend/src/app.tsx`)
- Gameplay view → 3D table renderer: renders (evidence: `frontend/src/game/gameplay.tsx`)
- Gameplay view → Game state store: uses (evidence: `frontend/src/game/gameplay.tsx`)
- 3D table renderer → Table scene: renders (evidence: `frontend/src/game/three-table.tsx`)
- 3D table renderer → Scene layout: builds layout (evidence: `frontend/src/game/three-table.tsx`)
- Table scene → Scene layout: uses (evidence: `frontend/src/game/three-table-scene.tsx`)
- Scene layout → Table geometry: uses (evidence: `frontend/src/game/three-table-layout.ts`)
- Replay workspace → Frontend API: requests replay data (evidence: `frontend/src/replay.tsx`)
- Match progression → Game domain: uses types (evidence: `crates/double_riichi_core/src/match_machine.rs`)
- Room runtime → Match progression: advances matches
- Room runtime → State projection: projects state
- Game engine → Legal decisions: computes actions
- HTTP service → Room runtime: dispatches room actions
- HTTP service → SQLite storage: persists records
- Authentication → SQLite storage: reads and writes (evidence: `crates/double_riichi_server/src/auth.rs`)
- Replay frames → MJSON codec: uses codec (evidence: `crates/double_riichi_replay/src/frames.rs`)
- Replay persistence → MJSON codec: encodes events (evidence: `crates/double_riichi_replay/src/persistence.rs`)
- MJAI adapter → Game engine: adapts game
- MCP interface → HTTP service: exposes tools
- ChatGPT gateway → MCP interface: connects tools
- OAuth integration → Authentication: supports sign-in
