# liliwqt/ai-defense-arena architecture

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

- Interactive diagram: https://gitdiagram.com/liliwqt/ai-defense-arena
- Repository: https://github.com/liliwqt/ai-defense-arena

## Overview

AI Defense Arena supports a multiplayer, source-grounded project defense: a host uploads project files, teammates join a room, and the team answers timed questions from four AI panelists before receiving shared coaching. The graph covers the multiplayer web flow and the documented Streamlit fallback. Backend routing and several UI behaviors are represented from the README and SOURCE INDEX; unsampled implementation details and unverified links are omitted.

Main entry points: [`game/src/App.tsx`](https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/App.tsx) (Arena app), [`game_server.py`](https://github.com/liliwqt/ai-defense-arena/blob/main/game_server.py) (Room server), [`question_generator.py`](https://github.com/liliwqt/ai-defense-arena/blob/main/question_generator.py) (Question and coaching AI), [`app.py`](https://github.com/liliwqt/ai-defense-arena/blob/main/app.py) (Streamlit app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Multiplayer web client"]
  node_app["Arena app<br/>[App.tsx]"]
  node_socket["Room connection<br/>[useRoomSocket.ts]"]
  node_controls["Room controls<br/>[ControlsPanel.tsx]"]
  node_dock["Vote and answer<br/>[RoomDock.tsx]"]
  node_composer["Answer composer<br/>[AnswerComposer.tsx]"]
  node_question["Question and citation<br/>[QuestionCard.tsx]"]
  node_hud["Room status<br/>[HUD.tsx]"]
  node_countdown["Deadline countdown"]
  node_scene["3D defense room"]
  node_transcript["Transcript drawer"]
  node_coaching_ui["Coaching report<br/>[CoachingReport.tsx]"]
end

subgraph group_room["Room runtime"]
  node_room_server["Room server<br/>[game_server.py]"]
  node_room_state[("Live room state<br/>[game_server.py]")]
end

subgraph group_defense["Defense engine"]
  node_uploads["Project file intake<br/>[project_files.py]"]
  node_session["Defense progression<br/>[defense_session.py]"]
  node_generator["Question and coaching AI"]
end

subgraph group_fallback["Streamlit fallback"]
  node_streamlit["Streamlit app<br/>[app.py]"]
end

node_host(("Host / defenders"))
node_openai{{"OpenAI service"}}

node_host -->|"uses"| node_app
node_app -->|"connects through"| node_socket
node_app -->|"renders"| node_controls
node_app -->|"renders"| node_dock
node_app -->|"renders"| node_question
node_app -->|"renders"| node_hud
node_app -->|"renders"| node_scene
node_app -->|"renders"| node_transcript
node_dock -->|"renders"| node_composer
node_hud -->|"uses"| node_countdown
node_host -->|"configures room"| node_controls
node_host -->|"votes and answers"| node_dock
node_socket -->|"WebSocket events"| node_room_server
node_room_server -->|"updates"| node_room_state
node_room_server -->|"accepts project files"| node_uploads
node_room_server -->|"advances defense"| node_session
node_session -->|"requests next move"| node_generator
node_generator -->|"reads project text"| node_uploads
node_generator -->|"generates questions and coaching"| node_openai
node_room_state -->|"sends room updates"| node_socket
node_app -->|"renders"| node_coaching_ui
node_transcript -->|"shows report"| node_coaching_ui
node_host -->|"uses fallback"| node_streamlit
node_streamlit -->|"reads project files"| node_uploads
node_streamlit -->|"starts and advances defense"| node_session

click node_app "https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/App.tsx"
click node_socket "https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/hooks/useRoomSocket.ts"
click node_controls "https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/ControlsPanel.tsx"
click node_dock "https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/RoomDock.tsx"
click node_composer "https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/AnswerComposer.tsx"
click node_question "https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/QuestionCard.tsx"
click node_hud "https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/HUD.tsx"
click node_countdown "https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/hooks/useRoomCountdown.ts"
click node_scene "https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/ThreeDefenseScene.tsx"
click node_transcript "https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/TranscriptPanel.tsx"
click node_coaching_ui "https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/CoachingReport.tsx"
click node_room_server "https://github.com/liliwqt/ai-defense-arena/blob/main/game_server.py"
click node_room_state "https://github.com/liliwqt/ai-defense-arena/blob/main/game_server.py"
click node_uploads "https://github.com/liliwqt/ai-defense-arena/blob/main/project_files.py"
click node_session "https://github.com/liliwqt/ai-defense-arena/blob/main/defense_session.py"
click node_generator "https://github.com/liliwqt/ai-defense-arena/blob/main/question_generator.py"
click node_streamlit "https://github.com/liliwqt/ai-defense-arena/blob/main/app.py"

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_app,node_socket,node_controls,node_dock,node_composer,node_question,node_hud,node_countdown,node_scene,node_transcript,node_coaching_ui toneBlue
class node_room_server,node_room_state toneAmber
class node_uploads,node_session,node_generator toneMint
class node_streamlit toneRose
class node_host,node_openai toneIndigo
```

## Components

### Multiplayer web client

- [Arena app](https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/App.tsx): `game/src/App.tsx`
- [Room connection](https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/hooks/useRoomSocket.ts): `game/src/hooks/useRoomSocket.ts`
- [Room controls](https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/ControlsPanel.tsx): `game/src/components/ControlsPanel.tsx`
- [Vote and answer](https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/RoomDock.tsx): `game/src/components/RoomDock.tsx`
- [Answer composer](https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/AnswerComposer.tsx): `game/src/components/AnswerComposer.tsx`
- [Question and citation](https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/QuestionCard.tsx): `game/src/components/QuestionCard.tsx`
- [Room status](https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/HUD.tsx): `game/src/components/HUD.tsx`
- [Deadline countdown](https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/hooks/useRoomCountdown.ts): `game/src/hooks/useRoomCountdown.ts`
- [3D defense room](https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/ThreeDefenseScene.tsx): `game/src/components/ThreeDefenseScene.tsx`
- [Transcript drawer](https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/TranscriptPanel.tsx): `game/src/components/TranscriptPanel.tsx`
- [Coaching report](https://github.com/liliwqt/ai-defense-arena/blob/main/game/src/components/CoachingReport.tsx): `game/src/components/CoachingReport.tsx`

### Room runtime

- [Room server](https://github.com/liliwqt/ai-defense-arena/blob/main/game_server.py): `game_server.py`
- [Live room state](https://github.com/liliwqt/ai-defense-arena/blob/main/game_server.py): `game_server.py`

### Defense engine

- [Project file intake](https://github.com/liliwqt/ai-defense-arena/blob/main/project_files.py): `project_files.py`
- [Defense progression](https://github.com/liliwqt/ai-defense-arena/blob/main/defense_session.py): `defense_session.py`
- [Question and coaching AI](https://github.com/liliwqt/ai-defense-arena/blob/main/question_generator.py): `question_generator.py`

### Streamlit fallback

- [Streamlit app](https://github.com/liliwqt/ai-defense-arena/blob/main/app.py): `app.py`

### Other components

- **Host / defenders**
- **OpenAI service**

## Connections

- Host / defenders → Arena app: uses (evidence: `README.md`)
- Arena app → Room connection: connects through (evidence: `game/src/App.tsx`)
- Arena app → Room controls: renders (evidence: `game/src/App.tsx`)
- Arena app → Vote and answer: renders (evidence: `game/src/App.tsx`)
- Arena app → Question and citation: renders (evidence: `game/src/App.tsx`)
- Arena app → Room status: renders (evidence: `game/src/App.tsx`)
- Arena app → 3D defense room: renders (evidence: `game/src/App.tsx`)
- Arena app → Transcript drawer: renders (evidence: `game/src/App.tsx`)
- Vote and answer → Answer composer: renders (evidence: `game/src/components/RoomDock.tsx`)
- Room status → Deadline countdown: uses (evidence: `game/src/components/HUD.tsx`)
- Host / defenders → Room controls: configures room (evidence: `README.md`)
- Host / defenders → Vote and answer: votes and answers (evidence: `README.md`)
- Room connection → Room server: WebSocket events (evidence: `README.md`)
- Room server → Live room state: updates (evidence: `README.md`)
- Room server → Project file intake: accepts project files (evidence: `README.md`)
- Room server → Defense progression: advances defense (evidence: `game_server.py`)
- Defense progression → Question and coaching AI: requests next move (evidence: `defense_session.py`)
- Question and coaching AI → Project file intake: reads project text (evidence: `question_generator.py`)
- Question and coaching AI → OpenAI service: generates questions and coaching (evidence: `README.md`)
- Live room state → Room connection: sends room updates (evidence: `README.md`)
- Arena app → Coaching report: renders (evidence: `game/src/App.tsx`)
- Transcript drawer → Coaching report: shows report (evidence: `game/src/components/TranscriptPanel.tsx`)
- Host / defenders → Streamlit app: uses fallback (evidence: `README.md`)
- Streamlit app → Project file intake: reads project files (evidence: `app.py`)
- Streamlit app → Defense progression: starts and advances defense (evidence: `app.py`)
