How kushvinth/zell works
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: main.py Backend API · App.tsx App shell · orchestrator.py Cycle orchestrator · executor.py Agent decision executor
Components 22
User experience
- App shell
frontend/src/App.tsx - API client
frontend/src/lib/api.ts - Run dashboard
frontend/src/components/EventDashboard.tsx - Simulation controls
frontend/src/components/ControlPanel.tsx - Atlas workbench
frontend/src/components/AtlasView.tsx - Relationship explorer
frontend/src/components/GraphPanel.tsx - World map
frontend/src/components/WorldMap.tsx
Agent bootstrap
- Persona generation
backend/app/services/llm_persona_generator.py - Batch bootstrap
backend/app/services/batch_generator.py - World landmarks
backend/app/data/landmarks.py
Simulation runtime
- Backend API
backend/main.py - Cycle orchestrator
backend/app/simulation/orchestrator.py - Agent decision executor
backend/app/simulation/executor.py - Agent model
backend/app/simulation/agent.py - Agent memory
backend/app/simulation/memory.py - Runtime agent store
backend/app/simulation/store.py - LLM service
backend/app/services/llm.py - Cycle aggregation
backend/app/simulation/aggregator.py
Knowledge and reporting
- Simulation database
backend/app/simulation/db.py - Hybrid search
backend/app/services/search.py - Report export
backend/app/services/report_export.py
Other components
- Operator
Connections 29
- Operator → App shell: uses
README.md - App shell → API client: requests
frontend/src/App.tsx - Simulation controls → API client: submits controls
frontend/src/components/ControlPanel.tsx - Run dashboard → API client: downloads reports
frontend/src/components/EventDashboard.tsx - Atlas workbench → Relationship explorer: shows graph
frontend/src/components/AtlasView.tsx - Atlas workbench → World map: shows map
frontend/src/components/AtlasView.tsx - App shell → Run dashboard: shows dashboard
frontend/src/App.tsx - App shell → Simulation controls: shows controls
frontend/src/App.tsx - App shell → Atlas workbench: shows atlas
frontend/src/App.tsx - API client → Backend API: calls API
README.md - Backend API → Batch bootstrap: starts batches
backend/main.py - Batch bootstrap → Persona generation: generates personas
backend/app/services/batch_generator.py - Persona generation → LLM service: generates sections
backend/app/services/llm_persona_generator.py - Backend API → Cycle orchestrator: starts runs
README.md - Cycle orchestrator → Agent decision executor: runs decisions
backend/app/simulation/orchestrator.py - Agent decision executor → Agent model: evaluates agent
backend/app/simulation/executor.py - Agent decision executor → Agent memory: uses memories
backend/app/simulation/executor.py - Agent decision executor → LLM service: requests reasoning
backend/app/simulation/executor.py - Cycle orchestrator → Simulation database: persists decisions
backend/app/simulation/orchestrator.py - Cycle orchestrator → Hybrid search: indexes responses
backend/app/simulation/orchestrator.py - Cycle orchestrator → Cycle aggregation: aggregates cycles
backend/app/simulation/orchestrator.py - Backend API → Simulation database: serves run data
README.md - Backend API → Hybrid search: serves search
README.md - Backend API → Report export: exports reports
backend/main.py - Hybrid search → Simulation database: reads indexed entries
backend/app/services/search.py - Report export → Simulation database: reads run records
backend/app/services/report_export.py - Runtime agent store → Agent model: stores agents
backend/app/simulation/store.py - Runtime agent store → Agent memory: stores memories
backend/app/simulation/store.py - Backend API → World landmarks: uses world data
README.md