# while-basic/agi-digital-city architecture

> Architecture diagram of the GitHub repository while-basic/agi-digital-city, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/while-basic/agi-digital-city
- Repository: https://github.com/while-basic/agi-digital-city

## Overview

##### Project Type and Purpose
- This is a Python‐based simulation framework (full-stack) that spawns 10–100 LLM-powered agents (“citizens”) in a closed digital city.
- It provides both a REST API and a web dashboard for monitoring, and uses FAISS+Obsidian for memory and logging.

##### File Structure
- Top-level scripts:
- run_simulation.py (entrypoint)
- src/ subpackages:
- agents/ (agent classes, emotion system, God agent)
- memory/ (FAISS index wrapper)
- simulation/ (town manager, asyncio loop)
- api/ (Flask REST endpoints)
- ui/ (Flask + JS dashboard, HTML templates)
- utils/ (database connector, LLM interface, Obsidian logger)
- config/ (configuration parameters)
- requirements.txt (.venv for Python env)
- project-docs/ (build & update guides)

##### README for Insights
- Core technologies: Python, asyncio, Flask, SQLite, FAISS, Obsidian API, Ollama LLM
- Runtime: one process may spawn multiple subprocesses or threads for I/O (LLM calls, memory writes)
- Ports: 5000 for API, 8080 for dashboard

##### Main Components
a. run_simulation.py (Orchestrator)
b. Simulation Engine (town_manager + asyncio scheduler)
c. Agent Pool (base_agent, emotion_system, god_agent)
d. Memory Backend
– FAISS Index (vector store for embeddings)
– Obsidian Vault (filesystem logs via obsidian_logger)
e. LLM Service (Ollama server with llama3.2:1b)
f. API Service (Flask)
g. UI Dashboard (Flask + JS, templates)
h. Database (SQLite via utils/database.py)
i. Configuration (config/config.py)

##### Relationships and Data Flows
- The Orchestrator invokes the Simulation Engine.
- The Simulation Engine schedules Agent behaviors each tick.
- Each Agent:
- Sends prompts to the LLM Service (via llm_interface).
- Retrieves/stores memories in FAISS (memory_system).
- Logs events to Obsidian vault.
- Persists state to SQLite.
- API Service exposes endpoints to query/update simulation state (talks to Simulation Engine and/or SQLite).
- UI Dashboard fetches data from the API Service and renders it in the browser.
- Configuration parameters flow into all components at startup.

##### Architectural Patterns & Principles
- Modular layering: Simulation core, Agents, Memory, API, UI
- Event-driven & asynchronous (asyncio) for high concurrency
- MVC for UI (Flask routes → templates → static assets)
- Adapter pattern in utils (wrapping FAISS, Obsidian, database, LLM calls)

##### Relevant Technologies
- Ollama LLM (external service)
- FAISS vector store
- Obsidian API (filesystem vault)
- Flask (API & Dashboard)
- SQLite (local file)
- Python asyncio

##### Final Checklist
- [ ] All major components are represented and labeled.
- [ ] Data flows and dependencies are arrowed and annotated.
- [ ] Architectural patterns (async, modular layering) are evident.
- [ ] Technologies and frameworks are noted.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration
    Configuration["Configuration<br/>(config/config.py)"]:::config
    click Configuration "https://github.com/while-basic/agi-digital-city/blob/main/config/config.py"

    %% Entry Point
    Orchestrator["Orchestrator<br/>(run_simulation.py)"]:::core
    click Orchestrator "https://github.com/while-basic/agi-digital-city/blob/main/run_simulation.py"
    Configuration --> Orchestrator

    MainModule["Main Module<br/>(src/main.py)"]:::core
    click MainModule "https://github.com/while-basic/agi-digital-city/blob/main/src/main.py"
    Orchestrator --> MainModule

    %% Backend Group
    subgraph "Backend" 
        direction TB
        SimulationEngine["Simulation Engine<br/>(town_manager + scheduler)"]:::core
        click SimulationEngine "https://github.com/while-basic/agi-digital-city/blob/main/src/simulation/town_manager.py"
        AgentPool["Agent Pool"]:::core
        subgraph "Agents"
            direction TB
            BaseAgent["Base Agent"]:::core
            click BaseAgent "https://github.com/while-basic/agi-digital-city/blob/main/src/agents/base_agent.py"
            EmotionSystem["Emotion System"]:::core
            click EmotionSystem "https://github.com/while-basic/agi-digital-city/blob/main/src/agents/emotion_system.py"
            GodAgent["God Agent"]:::core
            click GodAgent "https://github.com/while-basic/agi-digital-city/blob/main/src/agents/god_agent.py"
        end
        MemorySystem["FAISS Memory System"]:::storage
        click MemorySystem "https://github.com/while-basic/agi-digital-city/blob/main/src/memory/memory_system.py"
        ObsidianLogger["Obsidian Vault Logger"]:::storage
        click ObsidianLogger "https://github.com/while-basic/agi-digital-city/blob/main/src/utils/obsidian_logger.py"
        DatabaseConnector["SQLite Database"]:::storage
        click DatabaseConnector "https://github.com/while-basic/agi-digital-city/blob/main/src/utils/database.py"
        LLMInterface["LLM Service Adapter"]:::external
        click LLMInterface "https://github.com/while-basic/agi-digital-city/blob/main/src/utils/llm_interface.py"

        MainModule --> SimulationEngine
        SimulationEngine --> AgentPool

        AgentPool -->|async FAISS embed/query| MemorySystem
        AgentPool -->|async Obsidian write| ObsidianLogger
        AgentPool -->|async RPC calls| LLMInterface
        AgentPool -->|SQLite CRUD| DatabaseConnector
    end

    %% API & UI Group
    subgraph "API & Frontend"
        direction TB
        APIService["API Service<br/>(Flask REST)"]:::api
        click APIService "https://github.com/while-basic/agi-digital-city/blob/main/src/api/api.py"
        DashboardController["UI Dashboard Controller"]:::ui
        click DashboardController "https://github.com/while-basic/agi-digital-city/blob/main/src/ui/dashboard.py"
        HTMLTemplate["HTML Template"]:::ui
        click HTMLTemplate "https://github.com/while-basic/agi-digital-city/blob/main/src/ui/templates/index.html"

        SimulationEngine -->|internal call| APIService
        DatabaseConnector -->|SQLite read/write| APIService
        APIService -->|HTTP JSON| DashboardController
        DashboardController -->|renders| HTMLTemplate
    end

    %% External Service
    Ollama["Ollama LLM Server"]:::external
    LLMInterface -->|RPC| Ollama

    %% Styling
    classDef core fill:#D0E8FF,stroke:#1F78B4;
    classDef storage fill:#D5F5E3,stroke:#27AE60;
    classDef external fill:#FFE5B4,stroke:#E67E22;
    classDef api fill:#E8DAEF,stroke:#8E44AD;
    classDef ui fill:#FADBD8,stroke:#C0392B;
    classDef config fill:#FCF3CF,stroke:#B7950B;
```
