# romanslack/simuverse-test-environment-v1 architecture

> Architecture diagram of the GitHub repository romanslack/simuverse-test-environment-v1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/romanslack/simuverse-test-environment-v1
- Repository: https://github.com/romanslack/simuverse-test-environment-v1

## Overview

##### Project Type and Purpose
- SimuVerse is a full-stack, web-based, multi-agent simulation framework.
- Backend in Python manages agents, their movement, conversation logic.
- Frontend is delivered via Dash and JavaScript libraries (Cytoscape.js, vis-network).
- External LLM services (OpenAI, Claude, Hugging Face) supply agent conversational AI.

##### File Structure Analysis
- aiccontent/
- Pre-packaged agent behavior templates (CodingAgent, ExaSearch).
- modules/
- framework.py defines the BaseLLM, Agent, MultiAgentFramework abstractions.
- src/
- agent_manager.py orchestrates agent lifecycle and simulation loop.
- ui/
- simulation_grid_test.py and other test scripts launch the Dash app.
- lib/
- Third-party front-end assets: tom-select, vis-network, Cytoscape-style CSS.
- logs/
- conversations.log records chat history.
- requirements.txt and .env reference external dependencies (Dash, LLM SDKs).

##### Key Components
- User’s Browser (HTTP client)
- Dash Web Server (Python Flask under the hood)
- Simulation Backend
- Agent Manager
- MultiAgentFramework (in modules/framework.py)
- Agent State Store (in-memory; could be a future database)
- Movement & Conversation Engine
- Visualization Layer
- Cytoscape.js / vis-network renders grid and connections
- tom-select for UI controls
- External Services
- OpenAI API
- Claude API
- Hugging Face API
- Logging & Persistence
- conversations.log
- (Potential future DB)

##### Relationships and Data Flow
- Browser sends HTTP requests (Dash callbacks) → Dash Web Server.
- Web Server invokes simulation endpoints in src/ (agent_manager.py).
- Agent Manager calls MultiAgentFramework to update agent positions and conversation rounds.
- For each conversation step, MultiAgentFramework uses BaseLLM implementations to call external LLM APIs.
- Responses return to Agent Manager; state updates pushed to Visualization Layer.
- Browser renders updated grid and logs, user may adjust parameters → cycle repeats.
- Conversation text is appended to logs/conversations.log.

##### Architectural Patterns & Principles
- Modularization: clear separation of framework, simulation logic, content assets, and UI.
- Pluggable LLM Providers: BaseLLM interface allows easy swap/extension.
- MVC-style separation:
- Model: Agent state, conversation history
- View: Dash UI + JS visual libraries
- Controller: agent_manager.py, simulation callbacks
- Stateless HTTP layer with in-memory simulation engine (future stateful persistence recommended).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["User's Browser"]:::frontend
        DashServer["Dash Web Server"]:::frontend
        subgraph "UI Scripts"
            direction TB
            SimLaunch["simulation_grid_test.py"]:::frontend
            TestMain["test_main.py"]:::frontend
            TestAgents["test_agents.py"]:::frontend
            TestUI["test.py"]:::frontend
        end
        subgraph "Visualization Components"
            direction TB
            Cytoscape["Cytoscape.js"]:::frontend
            VisNetwork["vis-network.css"]:::frontend
            TomSelect["tom-select.css"]:::frontend
            BindUtils["bindings utils (JS)"]:::frontend
        end
    end

    %% Backend Services
    subgraph "Backend Services"
        direction TB
        AgentManager["Agent Manager"]:::backend
        MultiAgent["MultiAgentFramework & BaseLLM"]:::backend
        BehaviorTemplates["Pre-packaged Agent Behaviors"]:::backend
        VisualTransformer["Visualization Transformer"]:::backend
    end

    %% External Services
    subgraph "External LLM Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        Claude["Claude API"]:::external
        HF["Hugging Face API"]:::external
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        LogFile["conversations.log"]:::datastore
        FutureDB["Future DB (placeholder)"]:::datastore
        Requirements["requirements.txt"]:::datastore
    end

    %% Connections
    Browser -->|HTTP Requests| DashServer
    DashServer -->|callbacks| AgentManager
    AgentManager -->|update state| MultiAgent
    BehaviorTemplates -->|templates| MultiAgent
    MultiAgent -->|calls| OpenAI
    MultiAgent -->|calls| Claude
    MultiAgent -->|calls| HF
    MultiAgent -->|responses| AgentManager
    AgentManager -->|logs conversation| LogFile
    AgentManager -->|produces state| VisualTransformer
    VisualTransformer -->|JSON data| Browser
    Browser -->|renders grid| Cytoscape
    Browser -->|renders network| VisNetwork
    Browser -->|renders controls| TomSelect

    %% Testing & Assets links
    DashServer --> SimLaunch
    DashServer --> TestMain
    DashServer --> TestAgents
    DashServer --> TestUI
    Browser --> BindUtils

    %% Data store link
    Requirements --> DashServer

    %% Click Events
    click MultiAgent "https://github.com/romanslack/simuverse-test-environment-v1/blob/main/modules/framework.py"
    click AgentManager "https://github.com/romanslack/simuverse-test-environment-v1/blob/main/src/agent_manager.py"
    click VisualTransformer "https://github.com/romanslack/simuverse-test-environment-v1/blob/main/src/visualize.py"
    click BehaviorTemplates "https://github.com/romanslack/simuverse-test-environment-v1/tree/main/aiccontent/"
    click SimLaunch "https://github.com/romanslack/simuverse-test-environment-v1/blob/main/ui/simulation_grid_test.py"
    click TestUI "https://github.com/romanslack/simuverse-test-environment-v1/blob/main/ui/test.py"
    click TestAgents "https://github.com/romanslack/simuverse-test-environment-v1/blob/main/ui/test_agents.py"
    click TestMain "https://github.com/romanslack/simuverse-test-environment-v1/blob/main/ui/test_main.py"
    click VisNetwork "https://github.com/romanslack/simuverse-test-environment-v1/blob/main/lib/vis-9.1.2/vis-network.css"
    click TomSelect "https://github.com/romanslack/simuverse-test-environment-v1/blob/main/lib/tom-select/tom-select.css"
    click BindUtils "https://github.com/romanslack/simuverse-test-environment-v1/blob/main/lib/bindings/utils.js"
    click LogFile "https://github.com/romanslack/simuverse-test-environment-v1/blob/main/logs/conversations.log"
    click Requirements "https://github.com/romanslack/simuverse-test-environment-v1/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#98FB98,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef datastore fill:#D3D3D3,stroke:#000,stroke-width:1px
```
