# karpathy/llm-council architecture

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

- Interactive diagram: https://gitdiagram.com/karpathy/llm-council
- Repository: https://github.com/karpathy/llm-council

## Overview

LLM Council is a local web app for consulting multiple language models, comparing their anonymized peer evaluations, and presenting a chairman’s synthesis. A user submits a question through the chat; the backend runs and streams three distinct stages, while the app displays each result and persists the conversation. Users can also create and revisit conversations. The graph reflects the sampled streaming route and documented product capabilities; unsampled details are represented only where the README supports them.

Main entry points: [`backend/main.py`](https://github.com/karpathy/llm-council/blob/master/backend/main.py) (Conversation endpoints), [`backend/council.py`](https://github.com/karpathy/llm-council/blob/master/backend/council.py) (Council orchestration), [`frontend/src/components/ChatInterface.jsx`](https://github.com/karpathy/llm-council/blob/master/frontend/src/components/ChatInterface.jsx) (Chat interface), [`backend/openrouter.py`](https://github.com/karpathy/llm-council/blob/master/backend/openrouter.py) (OpenRouter client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_app["App state<br/>[App.jsx]"]
  node_sidebar["Conversation sidebar<br/>[Sidebar.jsx]"]
  node_chat["Chat interface<br/>[ChatInterface.jsx]"]
  node_stage1view["First opinions view<br/>[Stage1.jsx]"]
  node_stage2view["Peer rankings view<br/>[Stage2.jsx]"]
  node_stage3view["Final answer view<br/>[Stage3.jsx]"]
  node_apiclient["API client<br/>[api.js]"]
end

subgraph group_api["Conversation API"]
  node_httpapi["Conversation endpoints<br/>[main.py]"]
  node_storagecalls["Conversation operations<br/>[main.py]"]
end

subgraph group_council["Council workflow"]
  node_council["Council orchestration<br/>[council.py]"]
  node_first["First opinions<br/>[council.py]"]
  node_review["Anonymized peer review<br/>[council.py]"]
  node_aggregate["Aggregate rankings<br/>[council.py]"]
  node_chairman["Chairman synthesis<br/>[council.py]"]
  node_title["Conversation titling<br/>[council.py]"]
end

subgraph group_infra["Models and storage"]
  node_store[("JSON conversation store<br/>[storage.py]")]
  node_config["Council configuration<br/>[config.py]"]
  node_client["OpenRouter client<br/>[openrouter.py]"]
end

node_user(("User"))
node_openrouter{{"OpenRouter service"}}

node_user -->|"asks question"| node_chat
node_app -->|"renders"| node_sidebar
node_app -->|"renders"| node_chat
node_chat -->|"submits message"| node_app
node_app -->|"loads and streams"| node_apiclient
node_apiclient -->|"HTTP requests"| node_httpapi
node_httpapi -->|"handles conversations"| node_storagecalls
node_storagecalls -->|"reads and writes"| node_store
node_httpapi -->|"runs workflow"| node_council
node_httpapi -->|"collects stage one"| node_first
node_httpapi -->|"collects stage two"| node_review
node_httpapi -->|"calculates rankings"| node_aggregate
node_httpapi -->|"requests synthesis"| node_chairman
node_httpapi -->|"generates title"| node_title
node_council -->|"orchestrates"| node_first
node_council -->|"orchestrates"| node_review
node_council -->|"calculates"| node_aggregate
node_council -->|"orchestrates"| node_chairman
node_first -->|"queries models"| node_client
node_review -->|"queries models"| node_client
node_chairman -->|"queries chairman"| node_client
node_title -->|"queries title model"| node_client
node_client -->|"sends model requests"| node_openrouter
node_council -->|"uses model settings"| node_config
node_client -->|"uses API settings"| node_config
node_chat -->|"renders responses"| node_stage1view
node_chat -->|"renders rankings"| node_stage2view
node_chat -->|"renders synthesis"| node_stage3view

click node_app "https://github.com/karpathy/llm-council/blob/master/frontend/src/App.jsx"
click node_sidebar "https://github.com/karpathy/llm-council/blob/master/frontend/src/components/Sidebar.jsx"
click node_chat "https://github.com/karpathy/llm-council/blob/master/frontend/src/components/ChatInterface.jsx"
click node_stage1view "https://github.com/karpathy/llm-council/blob/master/frontend/src/components/Stage1.jsx"
click node_stage2view "https://github.com/karpathy/llm-council/blob/master/frontend/src/components/Stage2.jsx"
click node_stage3view "https://github.com/karpathy/llm-council/blob/master/frontend/src/components/Stage3.jsx"
click node_apiclient "https://github.com/karpathy/llm-council/blob/master/frontend/src/api.js"
click node_httpapi "https://github.com/karpathy/llm-council/blob/master/backend/main.py"
click node_storagecalls "https://github.com/karpathy/llm-council/blob/master/backend/main.py"
click node_store "https://github.com/karpathy/llm-council/blob/master/backend/storage.py"
click node_council "https://github.com/karpathy/llm-council/blob/master/backend/council.py"
click node_first "https://github.com/karpathy/llm-council/blob/master/backend/council.py"
click node_review "https://github.com/karpathy/llm-council/blob/master/backend/council.py"
click node_aggregate "https://github.com/karpathy/llm-council/blob/master/backend/council.py"
click node_chairman "https://github.com/karpathy/llm-council/blob/master/backend/council.py"
click node_title "https://github.com/karpathy/llm-council/blob/master/backend/council.py"
click node_config "https://github.com/karpathy/llm-council/blob/master/backend/config.py"
click node_client "https://github.com/karpathy/llm-council/blob/master/backend/openrouter.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_sidebar,node_chat,node_stage1view,node_stage2view,node_stage3view,node_apiclient,node_user toneBlue
class node_httpapi,node_storagecalls toneAmber
class node_council,node_first,node_review,node_aggregate,node_chairman,node_title,node_openrouter toneMint
class node_store,node_config,node_client toneRose
```

## Components

### Web interface

- [App state](https://github.com/karpathy/llm-council/blob/master/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Conversation sidebar](https://github.com/karpathy/llm-council/blob/master/frontend/src/components/Sidebar.jsx): `frontend/src/components/Sidebar.jsx`
- [Chat interface](https://github.com/karpathy/llm-council/blob/master/frontend/src/components/ChatInterface.jsx): `frontend/src/components/ChatInterface.jsx`
- [First opinions view](https://github.com/karpathy/llm-council/blob/master/frontend/src/components/Stage1.jsx): `frontend/src/components/Stage1.jsx`
- [Peer rankings view](https://github.com/karpathy/llm-council/blob/master/frontend/src/components/Stage2.jsx): `frontend/src/components/Stage2.jsx`
- [Final answer view](https://github.com/karpathy/llm-council/blob/master/frontend/src/components/Stage3.jsx): `frontend/src/components/Stage3.jsx`
- [API client](https://github.com/karpathy/llm-council/blob/master/frontend/src/api.js): `frontend/src/api.js`

### Conversation API

- [Conversation endpoints](https://github.com/karpathy/llm-council/blob/master/backend/main.py): `backend/main.py`
- [Conversation operations](https://github.com/karpathy/llm-council/blob/master/backend/main.py): `backend/main.py`

### Council workflow

- [Council orchestration](https://github.com/karpathy/llm-council/blob/master/backend/council.py): `backend/council.py`
- [First opinions](https://github.com/karpathy/llm-council/blob/master/backend/council.py): `backend/council.py`
- [Anonymized peer review](https://github.com/karpathy/llm-council/blob/master/backend/council.py): `backend/council.py`
- [Aggregate rankings](https://github.com/karpathy/llm-council/blob/master/backend/council.py): `backend/council.py`
- [Chairman synthesis](https://github.com/karpathy/llm-council/blob/master/backend/council.py): `backend/council.py`
- [Conversation titling](https://github.com/karpathy/llm-council/blob/master/backend/council.py): `backend/council.py`

### Models and storage

- [JSON conversation store](https://github.com/karpathy/llm-council/blob/master/backend/storage.py): `backend/storage.py`
- [Council configuration](https://github.com/karpathy/llm-council/blob/master/backend/config.py): `backend/config.py`
- [OpenRouter client](https://github.com/karpathy/llm-council/blob/master/backend/openrouter.py): `backend/openrouter.py`

### Other components

- **User**
- **OpenRouter service**

## Connections

- User → Chat interface: asks question (evidence: `frontend/src/components/ChatInterface.jsx`)
- App state → Conversation sidebar: renders (evidence: `frontend/src/App.jsx`)
- App state → Chat interface: renders (evidence: `frontend/src/App.jsx`)
- Chat interface → App state: submits message (evidence: `frontend/src/components/ChatInterface.jsx`)
- App state → API client: loads and streams (evidence: `frontend/src/App.jsx`)
- API client → Conversation endpoints: HTTP requests (evidence: `frontend/src/api.js`)
- Conversation endpoints → Conversation operations: handles conversations (evidence: `backend/main.py`)
- Conversation operations → JSON conversation store: reads and writes (evidence: `backend/main.py`)
- Conversation endpoints → Council orchestration: runs workflow (evidence: `backend/main.py`)
- Conversation endpoints → First opinions: collects stage one (evidence: `backend/main.py`)
- Conversation endpoints → Anonymized peer review: collects stage two (evidence: `backend/main.py`)
- Conversation endpoints → Aggregate rankings: calculates rankings (evidence: `backend/main.py`)
- Conversation endpoints → Chairman synthesis: requests synthesis (evidence: `backend/main.py`)
- Conversation endpoints → Conversation titling: generates title (evidence: `backend/main.py`)
- Council orchestration → First opinions: orchestrates (evidence: `backend/council.py`)
- Council orchestration → Anonymized peer review: orchestrates (evidence: `backend/council.py`)
- Council orchestration → Aggregate rankings: calculates (evidence: `backend/council.py`)
- Council orchestration → Chairman synthesis: orchestrates (evidence: `backend/council.py`)
- First opinions → OpenRouter client: queries models (evidence: `backend/council.py`)
- Anonymized peer review → OpenRouter client: queries models (evidence: `backend/council.py`)
- Chairman synthesis → OpenRouter client: queries chairman (evidence: `backend/council.py`)
- Conversation titling → OpenRouter client: queries title model (evidence: `backend/council.py`)
- OpenRouter client → OpenRouter service: sends model requests (evidence: `backend/openrouter.py`)
- Council orchestration → Council configuration: uses model settings (evidence: `backend/council.py`)
- OpenRouter client → Council configuration: uses API settings (evidence: `backend/openrouter.py`)
- Chat interface → First opinions view: renders responses (evidence: `frontend/src/components/ChatInterface.jsx`)
- Chat interface → Peer rankings view: renders rankings (evidence: `frontend/src/components/ChatInterface.jsx`)
- Chat interface → Final answer view: renders synthesis (evidence: `frontend/src/components/ChatInterface.jsx`)
