# kushvinth/zell architecture

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

## Overview

ZELL is a self-hosted multi-agent simulation and knowledge exploration platform. Users bootstrap personas and agents, configure and run event-driven simulation cycles, then inspect persisted decisions through dashboards, maps, relationship graphs, search, and report exports. The backend coordinates agent execution and memory, while the React frontend calls the API and presents results. The graph combines sampled calls and imports with README-documented capabilities; unsampled endpoint wiring and some feature-specific internals are not inferred.

Main entry points: [`backend/main.py`](https://github.com/kushvinth/zell/blob/main/backend/main.py) (Backend API), [`frontend/src/App.tsx`](https://github.com/kushvinth/zell/blob/main/frontend/src/App.tsx) (App shell), [`backend/app/simulation/orchestrator.py`](https://github.com/kushvinth/zell/blob/main/backend/app/simulation/orchestrator.py) (Cycle orchestrator), [`backend/app/simulation/executor.py`](https://github.com/kushvinth/zell/blob/main/backend/app/simulation/executor.py) (Agent decision executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["App shell<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_dashboard["Run dashboard<br/>[EventDashboard.tsx]"]
  node_control["Simulation controls<br/>[ControlPanel.tsx]"]
  node_atlas["Atlas workbench<br/>[AtlasView.tsx]"]
  node_graph_view["Relationship explorer<br/>[GraphPanel.tsx]"]
  node_world_map["World map<br/>[WorldMap.tsx]"]
end

subgraph group_bootstrap["Agent bootstrap"]
  node_persona_gen["Persona generation"]
  node_batch_gen["Batch bootstrap<br/>[batch_generator.py]"]
  node_landmarks["World landmarks<br/>[landmarks.py]"]
end

subgraph group_simulation["Simulation runtime"]
  node_backend_api["Backend API<br/>[main.py]"]
  node_orchestrator["Cycle orchestrator<br/>[orchestrator.py]"]
  node_executor["Agent decision executor<br/>[executor.py]"]
  node_agent["Agent model<br/>[agent.py]"]
  node_memory["Agent memory<br/>[memory.py]"]
  node_agent_store["Runtime agent store<br/>[store.py]"]
  node_llm["LLM service<br/>[llm.py]"]
  node_aggregator["Cycle aggregation<br/>[aggregator.py]"]
end

subgraph group_knowledge["Knowledge and reporting"]
  node_database[("Simulation database<br/>[db.py]")]
  node_search["Hybrid search<br/>[search.py]"]
  node_report_export["Report export<br/>[report_export.py]"]
end

node_user(("Operator"))

node_user -->|"uses"| node_app
node_app -->|"requests"| node_api_client
node_control -->|"submits controls"| node_api_client
node_dashboard -->|"downloads reports"| node_api_client
node_atlas -->|"shows graph"| node_graph_view
node_atlas -->|"shows map"| node_world_map
node_app -->|"shows dashboard"| node_dashboard
node_app -->|"shows controls"| node_control
node_app -->|"shows atlas"| node_atlas
node_api_client -->|"calls API"| node_backend_api
node_backend_api -->|"starts batches"| node_batch_gen
node_batch_gen -->|"generates personas"| node_persona_gen
node_persona_gen -->|"generates sections"| node_llm
node_backend_api -->|"starts runs"| node_orchestrator
node_orchestrator -->|"runs decisions"| node_executor
node_executor -->|"evaluates agent"| node_agent
node_executor -->|"uses memories"| node_memory
node_executor -->|"requests reasoning"| node_llm
node_orchestrator -->|"persists decisions"| node_database
node_orchestrator -->|"indexes responses"| node_search
node_orchestrator -->|"aggregates cycles"| node_aggregator
node_backend_api -->|"serves run data"| node_database
node_backend_api -->|"serves search"| node_search
node_backend_api -->|"exports reports"| node_report_export
node_search -->|"reads indexed entries"| node_database
node_report_export -->|"reads run records"| node_database
node_agent_store -->|"stores agents"| node_agent
node_agent_store -->|"stores memories"| node_memory
node_backend_api -->|"uses world data"| node_landmarks

click node_app "https://github.com/kushvinth/zell/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/kushvinth/zell/blob/main/frontend/src/lib/api.ts"
click node_dashboard "https://github.com/kushvinth/zell/blob/main/frontend/src/components/EventDashboard.tsx"
click node_control "https://github.com/kushvinth/zell/blob/main/frontend/src/components/ControlPanel.tsx"
click node_atlas "https://github.com/kushvinth/zell/blob/main/frontend/src/components/AtlasView.tsx"
click node_graph_view "https://github.com/kushvinth/zell/blob/main/frontend/src/components/GraphPanel.tsx"
click node_world_map "https://github.com/kushvinth/zell/blob/main/frontend/src/components/WorldMap.tsx"
click node_backend_api "https://github.com/kushvinth/zell/blob/main/backend/main.py"
click node_persona_gen "https://github.com/kushvinth/zell/blob/main/backend/app/services/llm_persona_generator.py"
click node_batch_gen "https://github.com/kushvinth/zell/blob/main/backend/app/services/batch_generator.py"
click node_landmarks "https://github.com/kushvinth/zell/blob/main/backend/app/data/landmarks.py"
click node_orchestrator "https://github.com/kushvinth/zell/blob/main/backend/app/simulation/orchestrator.py"
click node_executor "https://github.com/kushvinth/zell/blob/main/backend/app/simulation/executor.py"
click node_agent "https://github.com/kushvinth/zell/blob/main/backend/app/simulation/agent.py"
click node_memory "https://github.com/kushvinth/zell/blob/main/backend/app/simulation/memory.py"
click node_agent_store "https://github.com/kushvinth/zell/blob/main/backend/app/simulation/store.py"
click node_llm "https://github.com/kushvinth/zell/blob/main/backend/app/services/llm.py"
click node_database "https://github.com/kushvinth/zell/blob/main/backend/app/simulation/db.py"
click node_search "https://github.com/kushvinth/zell/blob/main/backend/app/services/search.py"
click node_aggregator "https://github.com/kushvinth/zell/blob/main/backend/app/simulation/aggregator.py"
click node_report_export "https://github.com/kushvinth/zell/blob/main/backend/app/services/report_export.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_api_client,node_dashboard,node_control,node_atlas,node_graph_view,node_world_map toneBlue
class node_persona_gen,node_batch_gen,node_landmarks toneAmber
class node_backend_api,node_orchestrator,node_executor,node_agent,node_memory,node_agent_store,node_llm,node_aggregator toneMint
class node_database,node_search,node_report_export toneRose
class node_user toneIndigo
```

## Components

### User experience

- [App shell](https://github.com/kushvinth/zell/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/kushvinth/zell/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Run dashboard](https://github.com/kushvinth/zell/blob/main/frontend/src/components/EventDashboard.tsx): `frontend/src/components/EventDashboard.tsx`
- [Simulation controls](https://github.com/kushvinth/zell/blob/main/frontend/src/components/ControlPanel.tsx): `frontend/src/components/ControlPanel.tsx`
- [Atlas workbench](https://github.com/kushvinth/zell/blob/main/frontend/src/components/AtlasView.tsx): `frontend/src/components/AtlasView.tsx`
- [Relationship explorer](https://github.com/kushvinth/zell/blob/main/frontend/src/components/GraphPanel.tsx): `frontend/src/components/GraphPanel.tsx`
- [World map](https://github.com/kushvinth/zell/blob/main/frontend/src/components/WorldMap.tsx): `frontend/src/components/WorldMap.tsx`

### Agent bootstrap

- [Persona generation](https://github.com/kushvinth/zell/blob/main/backend/app/services/llm_persona_generator.py): `backend/app/services/llm_persona_generator.py`
- [Batch bootstrap](https://github.com/kushvinth/zell/blob/main/backend/app/services/batch_generator.py): `backend/app/services/batch_generator.py`
- [World landmarks](https://github.com/kushvinth/zell/blob/main/backend/app/data/landmarks.py): `backend/app/data/landmarks.py`

### Simulation runtime

- [Backend API](https://github.com/kushvinth/zell/blob/main/backend/main.py): `backend/main.py`
- [Cycle orchestrator](https://github.com/kushvinth/zell/blob/main/backend/app/simulation/orchestrator.py): `backend/app/simulation/orchestrator.py`
- [Agent decision executor](https://github.com/kushvinth/zell/blob/main/backend/app/simulation/executor.py): `backend/app/simulation/executor.py`
- [Agent model](https://github.com/kushvinth/zell/blob/main/backend/app/simulation/agent.py): `backend/app/simulation/agent.py`
- [Agent memory](https://github.com/kushvinth/zell/blob/main/backend/app/simulation/memory.py): `backend/app/simulation/memory.py`
- [Runtime agent store](https://github.com/kushvinth/zell/blob/main/backend/app/simulation/store.py): `backend/app/simulation/store.py`
- [LLM service](https://github.com/kushvinth/zell/blob/main/backend/app/services/llm.py): `backend/app/services/llm.py`
- [Cycle aggregation](https://github.com/kushvinth/zell/blob/main/backend/app/simulation/aggregator.py): `backend/app/simulation/aggregator.py`

### Knowledge and reporting

- [Simulation database](https://github.com/kushvinth/zell/blob/main/backend/app/simulation/db.py): `backend/app/simulation/db.py`
- [Hybrid search](https://github.com/kushvinth/zell/blob/main/backend/app/services/search.py): `backend/app/services/search.py`
- [Report export](https://github.com/kushvinth/zell/blob/main/backend/app/services/report_export.py): `backend/app/services/report_export.py`

### Other components

- **Operator**

## Connections

- Operator → App shell: uses (evidence: `README.md`)
- App shell → API client: requests (evidence: `frontend/src/App.tsx`)
- Simulation controls → API client: submits controls (evidence: `frontend/src/components/ControlPanel.tsx`)
- Run dashboard → API client: downloads reports (evidence: `frontend/src/components/EventDashboard.tsx`)
- Atlas workbench → Relationship explorer: shows graph (evidence: `frontend/src/components/AtlasView.tsx`)
- Atlas workbench → World map: shows map (evidence: `frontend/src/components/AtlasView.tsx`)
- App shell → Run dashboard: shows dashboard (evidence: `frontend/src/App.tsx`)
- App shell → Simulation controls: shows controls (evidence: `frontend/src/App.tsx`)
- App shell → Atlas workbench: shows atlas (evidence: `frontend/src/App.tsx`)
- API client → Backend API: calls API (evidence: `README.md`)
- Backend API → Batch bootstrap: starts batches (evidence: `backend/main.py`)
- Batch bootstrap → Persona generation: generates personas (evidence: `backend/app/services/batch_generator.py`)
- Persona generation → LLM service: generates sections (evidence: `backend/app/services/llm_persona_generator.py`)
- Backend API → Cycle orchestrator: starts runs (evidence: `README.md`)
- Cycle orchestrator → Agent decision executor: runs decisions (evidence: `backend/app/simulation/orchestrator.py`)
- Agent decision executor → Agent model: evaluates agent (evidence: `backend/app/simulation/executor.py`)
- Agent decision executor → Agent memory: uses memories (evidence: `backend/app/simulation/executor.py`)
- Agent decision executor → LLM service: requests reasoning (evidence: `backend/app/simulation/executor.py`)
- Cycle orchestrator → Simulation database: persists decisions (evidence: `backend/app/simulation/orchestrator.py`)
- Cycle orchestrator → Hybrid search: indexes responses (evidence: `backend/app/simulation/orchestrator.py`)
- Cycle orchestrator → Cycle aggregation: aggregates cycles (evidence: `backend/app/simulation/orchestrator.py`)
- Backend API → Simulation database: serves run data (evidence: `README.md`)
- Backend API → Hybrid search: serves search (evidence: `README.md`)
- Backend API → Report export: exports reports (evidence: `backend/main.py`)
- Hybrid search → Simulation database: reads indexed entries (evidence: `backend/app/services/search.py`)
- Report export → Simulation database: reads run records (evidence: `backend/app/services/report_export.py`)
- Runtime agent store → Agent model: stores agents (evidence: `backend/app/simulation/store.py`)
- Runtime agent store → Agent memory: stores memories (evidence: `backend/app/simulation/store.py`)
- Backend API → World landmarks: uses world data (evidence: `README.md`)
