# tejabasina/ai-multi-agent-debate architecture

> Architecture diagram of the GitHub repository tejabasina/ai-multi-agent-debate, 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/tejabasina/ai-multi-agent-debate
- Repository: https://github.com/tejabasina/ai-multi-agent-debate

## Overview

AI Multi-Agent Debate System: users sign in, submit a topic, watch two agents debate over WebSocket, and receive a judge’s scored verdict. Debates are persisted for history and replay; the interface also supports translation, analytics, and an animated 3D presentation. The graph follows documented architecture and sampled calls; some page-to-API and database details are inferred only where README capabilities support them, so uncertain wiring is omitted.

Main entry points: [`backend/server.js`](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/server.js) (HTTP / WS server), [`backend/orchestrator.js`](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/orchestrator.js) (Debate orchestrator), [`frontend/src/context/DebateContext.jsx`](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/context/DebateContext.jsx) (Debate context), [`frontend/src/pages/DebatePage.jsx`](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/DebatePage.jsx) (Debate view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_authui["Login / signup<br/>[LandingPage.jsx]"]
  node_home["Debate workspace<br/>[Home.jsx]"]
  node_context["Debate context<br/>[DebateContext.jsx]"]
  node_debatepage["Debate view<br/>[DebatePage.jsx]"]
  node_scene["3D debate scene<br/>[DebateScene3D.jsx]"]
  node_history["History / replay<br/>[HistoryPage.jsx]"]
  node_analytics["Analytics view<br/>[AnalyticsPage.jsx]"]
  node_about["About page<br/>[AboutPage.jsx]"]
end

subgraph group_backend["Backend services"]
  node_server["HTTP / WS server<br/>[server.js]"]
  node_auth["JWT verification<br/>[authMiddleware.js]"]
end

subgraph group_debate["Debate runtime"]
  node_orchestrator["Debate orchestrator<br/>[orchestrator.js]"]
  node_agents["Agent prompts<br/>[agents.js]"]
  node_claude["Claude client<br/>[claudeClient.js]"]
end

subgraph group_data["Persistence"]
  node_database[("SQLite database<br/>[db.js]")]
end

node_user(("User"))
node_anthropic["Anthropic API"]

node_user -->|"signs in"| node_authui
node_user -->|"enters topic"| node_home
node_authui -->|"authenticates"| node_server
node_server -->|"reads / writes users"| node_database
node_server -->|"verifies token"| node_auth
node_home -->|"starts debate"| node_context
node_context -->|"opens WebSocket"| node_server
node_server -->|"runs debate"| node_orchestrator
node_orchestrator -->|"uses prompts"| node_agents
node_orchestrator -->|"requests completions"| node_claude
node_claude -.->|"calls API"| node_anthropic
node_orchestrator -->|"saves debate"| node_database
node_server -->|"streams events"| node_context
node_context -->|"provides state"| node_debatepage
node_debatepage -->|"sets speaker / verdict"| node_scene
node_history -->|"requests debates"| node_server
node_debatepage -->|"requests translation"| node_server
node_server -->|"translates text"| node_claude
node_analytics -->|"requests metrics"| node_server
node_server -->|"reads metrics"| node_database

click node_authui "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/LandingPage.jsx"
click node_home "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/Home.jsx"
click node_context "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/context/DebateContext.jsx"
click node_debatepage "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/DebatePage.jsx"
click node_scene "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/components/DebateScene3D.jsx"
click node_history "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/HistoryPage.jsx"
click node_analytics "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/AnalyticsPage.jsx"
click node_server "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/server.js"
click node_auth "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/authMiddleware.js"
click node_orchestrator "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/orchestrator.js"
click node_agents "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/agents.js"
click node_claude "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/claudeClient.js"
click node_database "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/db.js"
click node_about "https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/AboutPage.jsx"

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_authui,node_home,node_context,node_debatepage,node_scene,node_history,node_analytics,node_about,node_user toneBlue
class node_server,node_auth toneAmber
class node_orchestrator,node_agents,node_claude,node_anthropic toneMint
class node_database toneRose
```

## Components

### Web experience

- [Login / signup](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/LandingPage.jsx): `frontend/src/pages/LandingPage.jsx`
- [Debate workspace](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/Home.jsx): `frontend/src/pages/Home.jsx`
- [Debate context](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/context/DebateContext.jsx): `frontend/src/context/DebateContext.jsx`
- [Debate view](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/DebatePage.jsx): `frontend/src/pages/DebatePage.jsx`
- [3D debate scene](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/components/DebateScene3D.jsx): `frontend/src/components/DebateScene3D.jsx`
- [History / replay](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/HistoryPage.jsx): `frontend/src/pages/HistoryPage.jsx`
- [Analytics view](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/AnalyticsPage.jsx): `frontend/src/pages/AnalyticsPage.jsx`
- [About page](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/frontend/src/pages/AboutPage.jsx): `frontend/src/pages/AboutPage.jsx`

### Backend services

- [HTTP / WS server](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/server.js): `backend/server.js`
- [JWT verification](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/authMiddleware.js): `backend/authMiddleware.js`

### Debate runtime

- [Debate orchestrator](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/orchestrator.js): `backend/orchestrator.js`
- [Agent prompts](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/agents.js): `backend/agents.js`
- [Claude client](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/claudeClient.js): `backend/claudeClient.js`

### Persistence

- [SQLite database](https://github.com/tejabasina/ai-multi-agent-debate/blob/main/backend/db.js): `backend/db.js`

### Other components

- **User**
- **Anthropic API**

## Connections

- User → Login / signup: signs in
- User → Debate workspace: enters topic
- Login / signup → HTTP / WS server: authenticates
- HTTP / WS server → SQLite database: reads / writes users
- HTTP / WS server → JWT verification: verifies token
- Debate workspace → Debate context: starts debate
- Debate context → HTTP / WS server: opens WebSocket
- HTTP / WS server → Debate orchestrator: runs debate
- Debate orchestrator → Agent prompts: uses prompts
- Debate orchestrator → Claude client: requests completions
- Claude client → Anthropic API: calls API
- Debate orchestrator → SQLite database: saves debate
- HTTP / WS server → Debate context: streams events
- Debate context → Debate view: provides state
- Debate view → 3D debate scene: sets speaker / verdict
- History / replay → HTTP / WS server: requests debates
- Debate view → HTTP / WS server: requests translation
- HTTP / WS server → Claude client: translates text
- Analytics view → HTTP / WS server: requests metrics
- HTTP / WS server → SQLite database: reads metrics