# asadulm/agora architecture

> Architecture diagram of the GitHub repository asadulm/agora, 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/asadulm/agora
- Repository: https://github.com/asadulm/agora

## Overview

AGORA is a self-hosted, document-grounded multi-agent debate platform. Users authenticate, configure agents and documents, start a debate, then inspect its staged reasoning, evidence, and final moderator verdict in a real-time workspace; follow-up cycles extend that discussion. The graph emphasizes the documented execution and RAG paths, plus authentication, presets, and live updates. Some backend routes and integrations are unsampled, so their connections are included only where the README or source index supports them.

Main entry points: [`server/app/services/debate_engine/round_manager.py`](https://github.com/asadulm/agora/blob/main/server/app/services/debate_engine/round_manager.py) (Debate stages), [`server/app/main.py`](https://github.com/asadulm/agora/blob/main/server/app/main.py) (FastAPI application), [`client/src/features/debate/ui`](https://github.com/asadulm/agora/tree/main/client/src/features/debate/ui) (Debate workspace), [`server/app/services/chat_engine.py`](https://github.com/asadulm/agora/blob/main/server/app/services/chat_engine.py) (Turn orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_workspace["Debate workspace"]
  node_debate_state["Debate state<br/>[debate.store.ts]"]
  node_auth_client["Authentication client<br/>[authService.ts]"]
  node_presets_client["Agent presets"]
end

subgraph group_api["API and identity"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_debate_routes["Debate routes<br/>[debate.py]"]
  node_document_routes["Document routes<br/>[documents.py]"]
  node_preset_routes["Preset routes<br/>[agent_presets.py]"]
  node_ws_routes["WebSocket routes<br/>[ws.py]"]
end

subgraph group_execution["Debate execution"]
  node_chat_engine["Turn orchestration<br/>[chat_engine.py]"]
  node_round_manager["Debate stages<br/>[round_manager.py]"]
  node_followup_runner["Follow-up cycles<br/>[followup_runner.py]"]
  node_topic_guard["Topic validation"]
end

subgraph group_knowledge["Documents and retrieval"]
  node_ingestion["Document ingestion"]
  node_retrieval["Evidence retrieval"]
  node_embedding["Embedding service"]
end

subgraph group_infrastructure["Models and integrations"]
  node_db[("PostgreSQL and pgvector")]
  node_llm["LLM provider router"]
  node_ws_manager["WebSocket manager<br/>[ws_manager.py]"]
  node_storage["Document storage"]
  node_llm_providers["LLM providers"]
end

node_user(("User"))

node_user -->|"uses"| node_workspace
node_workspace -->|"updates"| node_debate_state
node_workspace -->|"starts debates"| node_debate_routes
node_workspace -->|"uploads documents"| node_document_routes
node_workspace -->|"subscribes live"| node_ws_routes
node_auth_client -->|"authenticates"| node_auth_routes
node_presets_client -->|"loads presets"| node_preset_routes
node_api_app -->|"registers"| node_auth_routes
node_api_app -->|"registers"| node_debate_routes
node_api_app -->|"registers"| node_document_routes
node_api_app -->|"registers"| node_preset_routes
node_api_app -->|"registers"| node_ws_routes
node_debate_routes -->|"starts execution"| node_chat_engine
node_chat_engine -->|"runs stages"| node_round_manager
node_chat_engine -->|"loads and saves"| node_db
node_chat_engine -->|"publishes progress"| node_ws_manager
node_round_manager -->|"requests evidence"| node_retrieval
node_round_manager -->|"generates responses"| node_llm
node_round_manager -->|"persists stages"| node_db
node_round_manager -->|"emits progress"| node_ws_manager
node_retrieval -->|"embeds query"| node_embedding
node_retrieval -->|"searches chunks"| node_db
node_document_routes -->|"processes uploads"| node_ingestion
node_ingestion -->|"embeds chunks"| node_embedding
node_ingestion -->|"stores originals"| node_storage
node_ingestion -->|"stores document data"| node_db
node_llm -->|"routes requests"| node_llm_providers
node_followup_runner -->|"executes follow-up"| node_round_manager
node_debate_routes -->|"validates topics"| node_topic_guard

click node_workspace "https://github.com/asadulm/agora/tree/main/client/src/features/debate/ui"
click node_debate_state "https://github.com/asadulm/agora/blob/main/client/src/features/debate/model/debate.store.ts"
click node_auth_client "https://github.com/asadulm/agora/blob/main/client/src/services/authService.ts"
click node_presets_client "https://github.com/asadulm/agora/tree/main/client/src/features/agent-presets"
click node_api_app "https://github.com/asadulm/agora/blob/main/server/app/main.py"
click node_auth_routes "https://github.com/asadulm/agora/blob/main/server/app/api/routes/auth.py"
click node_debate_routes "https://github.com/asadulm/agora/blob/main/server/app/api/routes/debate.py"
click node_document_routes "https://github.com/asadulm/agora/blob/main/server/app/api/routes/documents.py"
click node_preset_routes "https://github.com/asadulm/agora/blob/main/server/app/api/routes/agent_presets.py"
click node_ws_routes "https://github.com/asadulm/agora/blob/main/server/app/api/routes/ws.py"
click node_chat_engine "https://github.com/asadulm/agora/blob/main/server/app/services/chat_engine.py"
click node_round_manager "https://github.com/asadulm/agora/blob/main/server/app/services/debate_engine/round_manager.py"
click node_followup_runner "https://github.com/asadulm/agora/blob/main/server/app/services/followup_runner.py"
click node_topic_guard "https://github.com/asadulm/agora/blob/main/server/app/services/topic_guard/topic_guard_service.py"
click node_ingestion "https://github.com/asadulm/agora/blob/main/server/app/services/documents/ingestion_service.py"
click node_retrieval "https://github.com/asadulm/agora/blob/main/server/app/services/retrieval/retrieval_service.py"
click node_embedding "https://github.com/asadulm/agora/blob/main/server/app/services/embeddings/embedding_service.py"
click node_llm "https://github.com/asadulm/agora/tree/main/server/app/services/llm"
click node_ws_manager "https://github.com/asadulm/agora/blob/main/server/app/services/ws_manager.py"
click node_storage "https://github.com/asadulm/agora/tree/main/server/app/services/storage"
click node_llm_providers "https://github.com/asadulm/agora/tree/main/server/app/services/llm/providers"

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_workspace,node_debate_state,node_auth_client,node_presets_client,node_user toneBlue
class node_api_app,node_auth_routes,node_debate_routes,node_document_routes,node_preset_routes,node_ws_routes toneAmber
class node_chat_engine,node_round_manager,node_followup_runner,node_topic_guard toneMint
class node_ingestion,node_retrieval,node_embedding toneRose
class node_db,node_llm,node_ws_manager,node_storage,node_llm_providers toneIndigo
```

## Components

### Web client

- [Debate workspace](https://github.com/asadulm/agora/tree/main/client/src/features/debate/ui): `client/src/features/debate/ui`
- [Debate state](https://github.com/asadulm/agora/blob/main/client/src/features/debate/model/debate.store.ts): `client/src/features/debate/model/debate.store.ts`
- [Authentication client](https://github.com/asadulm/agora/blob/main/client/src/services/authService.ts): `client/src/services/authService.ts`
- [Agent presets](https://github.com/asadulm/agora/tree/main/client/src/features/agent-presets): `client/src/features/agent-presets`

### API and identity

- [FastAPI application](https://github.com/asadulm/agora/blob/main/server/app/main.py): `server/app/main.py`
- [Authentication routes](https://github.com/asadulm/agora/blob/main/server/app/api/routes/auth.py): `server/app/api/routes/auth.py`
- [Debate routes](https://github.com/asadulm/agora/blob/main/server/app/api/routes/debate.py): `server/app/api/routes/debate.py`
- [Document routes](https://github.com/asadulm/agora/blob/main/server/app/api/routes/documents.py): `server/app/api/routes/documents.py`
- [Preset routes](https://github.com/asadulm/agora/blob/main/server/app/api/routes/agent_presets.py): `server/app/api/routes/agent_presets.py`
- [WebSocket routes](https://github.com/asadulm/agora/blob/main/server/app/api/routes/ws.py): `server/app/api/routes/ws.py`

### Debate execution

- [Turn orchestration](https://github.com/asadulm/agora/blob/main/server/app/services/chat_engine.py): `server/app/services/chat_engine.py`
- [Debate stages](https://github.com/asadulm/agora/blob/main/server/app/services/debate_engine/round_manager.py): `server/app/services/debate_engine/round_manager.py`
- [Follow-up cycles](https://github.com/asadulm/agora/blob/main/server/app/services/followup_runner.py): `server/app/services/followup_runner.py`
- [Topic validation](https://github.com/asadulm/agora/blob/main/server/app/services/topic_guard/topic_guard_service.py): `server/app/services/topic_guard/topic_guard_service.py`

### Documents and retrieval

- [Document ingestion](https://github.com/asadulm/agora/blob/main/server/app/services/documents/ingestion_service.py): `server/app/services/documents/ingestion_service.py`
- [Evidence retrieval](https://github.com/asadulm/agora/blob/main/server/app/services/retrieval/retrieval_service.py): `server/app/services/retrieval/retrieval_service.py`
- [Embedding service](https://github.com/asadulm/agora/blob/main/server/app/services/embeddings/embedding_service.py): `server/app/services/embeddings/embedding_service.py`

### Models and integrations

- **PostgreSQL and pgvector**
- [LLM provider router](https://github.com/asadulm/agora/tree/main/server/app/services/llm): `server/app/services/llm`
- [WebSocket manager](https://github.com/asadulm/agora/blob/main/server/app/services/ws_manager.py): `server/app/services/ws_manager.py`
- [Document storage](https://github.com/asadulm/agora/tree/main/server/app/services/storage): `server/app/services/storage`
- [LLM providers](https://github.com/asadulm/agora/tree/main/server/app/services/llm/providers): `server/app/services/llm/providers`

### Other components

- **User**

## Connections

- User → Debate workspace: uses (evidence: `README.md`)
- Debate workspace → Debate state: updates (evidence: `client/src/features/debate/model/debate.store.ts`)
- Debate workspace → Debate routes: starts debates (evidence: `README.md`)
- Debate workspace → Document routes: uploads documents (evidence: `README.md`)
- Debate workspace → WebSocket routes: subscribes live (evidence: `README.md`)
- Authentication client → Authentication routes: authenticates (evidence: `README.md`)
- Agent presets → Preset routes: loads presets (evidence: `README.md`)
- FastAPI application → Authentication routes: registers (evidence: `server/app/main.py`)
- FastAPI application → Debate routes: registers (evidence: `server/app/main.py`)
- FastAPI application → Document routes: registers (evidence: `server/app/main.py`)
- FastAPI application → Preset routes: registers (evidence: `server/app/main.py`)
- FastAPI application → WebSocket routes: registers (evidence: `server/app/main.py`)
- Debate routes → Turn orchestration: starts execution (evidence: `README.md`)
- Turn orchestration → Debate stages: runs stages (evidence: `server/app/services/chat_engine.py`)
- Turn orchestration → PostgreSQL and pgvector: loads and saves (evidence: `README.md`)
- Turn orchestration → WebSocket manager: publishes progress (evidence: `README.md`)
- Debate stages → Evidence retrieval: requests evidence (evidence: `server/app/services/retrieval/retrieval_service.py`)
- Debate stages → LLM provider router: generates responses (evidence: `README.md`)
- Debate stages → PostgreSQL and pgvector: persists stages (evidence: `README.md`)
- Debate stages → WebSocket manager: emits progress (evidence: `README.md`)
- Evidence retrieval → Embedding service: embeds query (evidence: `server/app/services/retrieval/retrieval_service.py`)
- Evidence retrieval → PostgreSQL and pgvector: searches chunks (evidence: `server/app/services/retrieval/retrieval_service.py`)
- Document routes → Document ingestion: processes uploads (evidence: `server/app/services/documents/ingestion_service.py`)
- Document ingestion → Embedding service: embeds chunks (evidence: `server/app/services/documents/ingestion_service.py`)
- Document ingestion → Document storage: stores originals (evidence: `server/app/services/documents/ingestion_service.py`)
- Document ingestion → PostgreSQL and pgvector: stores document data (evidence: `server/app/services/documents/ingestion_service.py`)
- LLM provider router → LLM providers: routes requests (evidence: `server/app/services/llm/service.py`)
- Follow-up cycles → Debate stages: executes follow-up (evidence: `README.md`)
- Debate routes → Topic validation: validates topics (evidence: `README.md`)
