# neolaf2/society_zero_universe architecture

> Architecture diagram of the GitHub repository neolaf2/society_zero_universe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neolaf2/society_zero_universe
- Repository: https://github.com/neolaf2/society_zero_universe

## Overview

##### Project Type & Purpose
- This is a full-stack AI-driven social-science simulation platform (“Society Zero Universe”)
- Frontend: Next.js + React + TypeScript + Tailwind – user interface for experiment design, execution, and visualization
- Backend: FastAPI (Python) – REST API layer, request routing, authentication, health checks
- Core domain: Business logic in `core/`, orchestrates agents, environments, experiments
- Shared libraries in `libs/`: simulation engine (`simengine`), agent framework (`agent`), Docker sandbox executor

##### File-Structure & Architectural Patterns
- Top level:
- api/ — API controllers (FastAPI) → routers, middleware, exception handlers
- core/ — domain managers & services → agent_manager, conversation_manager, sandbox_manager, project_manager, plus plugin sub-directories
- frontend/ — Next.js app → `app/` routes, `components/`, `lib/`, hooks, and static/public assets
- libs/ — reusable libraries → `simengine` (multi-agent simulation), `agent` (LLM-driven agent framework), `docker_sandbox` (container isolation)
- scripts/ — Docker image build
- Layered MVC–style separation:
- Presentation (frontend)
- API (api/)
- Service layer (core/services, core/managers, core/plugins)
- Libraries (libs/)
- Persistence (file-based or database under data/, not shown explicitly)

a. Main Components
1. Frontend UI (Next.js)
2. API Layer (FastAPI)
3. Business-Logic Core
– Managers: project_manager, sandbox_manager, experiment_coordinator
– Services: agent_sets_service, schedules_service, model_configuration_service, etc.
– Plugins: resource plugins (agent_set_handler, logic_handler), workflow plugins
4. Simulation Engine (libs/simengine)
5. Agent Framework (libs/agent)
6. Docker Sandbox Executor (libs/docker_sandbox)
7. Data Store (projects, user data – e.g., PostgreSQL or file storage)
8. External Dependencies: LLM providers (OpenAI, Anthropic), Docker daemon
b. Relationships & Data Flows
- Frontend ↔ Backend: HTTP/REST (+ WebSockets if used)
- Backend API controllers → Core Services / Managers (in-process calls)
- Core Managers → Simulation Engine & Agent Framework (library calls)
- Simulation Engine runs multi-agent loops / event pipeline
- Agent Framework implements AI agent behaviors via LLM calls
- Docker Sandbox invoked by Sandbox Manager to isolate code/notebooks
- Core Services persist experiment definitions & results to Data Store
- Frontend fetches experiment data, streams logs & metrics for visualization
c. Architectural Patterns & Principles
- Layered architecture (Presentation → API → Service → Domain → Infrastructure)
- Plugin architecture for resource handlers & workflows
- Dependency injection in FastAPI (`core/dependencies.py`)
- Loose coupling: shared libraries (libs/) extracted for reuse
- Sandbox isolation: container-based security boundary
d. Key Technologies
- Frontend: Next.js, React, TypeScript, Tailwind CSS, Radix UI
- Backend: Python 3.12+, FastAPI, Uvicorn, Pydantic
- Simulation: Custom multi-agent simengine (async event pipeline)
- Agents: LLM-driven agent framework (OpenAI, Anthropic connectors)
- Infrastructure: Docker, Docker Compose, pnpm, PostgreSQL (or file store)

##### Detailed Elements to Capture
- Frontend modules: routes under `app/`, key client-side services (chat-service, project-service)
- API routers: agents, experiments, environments, schedules
- Core plugins: resource handlers & workflow YAML definitions
- Library boundaries: simengine vs. agent vs. sandbox
- External calls: LLM API, Docker daemon
- Persistence layer (DB or file store)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        User["User & Browser"]:::external
    end

    %% Frontend
    subgraph "Presentation Layer"
        Frontend["Frontend UI (Next.js)"]:::frontend
    end
    User -->|"HTTP/WebSocket"| Frontend
    click Frontend "https://github.com/neolaf2/society_zero_universe/tree/main/frontend/"

    %% API Layer
    subgraph "API Layer"
        API["FastAPI API Layer"]:::api
        Routers["API Routers & Controllers"]:::api
        API --> Routers
    end
    Frontend -->|"HTTP/REST"| API
    click API "https://github.com/neolaf2/society_zero_universe/blob/main/api/main.py"
    click Routers "https://github.com/neolaf2/society_zero_universe/tree/main/api/routers/"
    click API "https://github.com/neolaf2/society_zero_universe/blob/main/api/components/auth_middleware.py"
    click API "https://github.com/neolaf2/society_zero_universe/tree/main/api/services/"

    %% Core Business Logic
    subgraph "Core Business Logic"
        PM["ProjectManager"]:::core
        AM["AgentManager"]:::core
        CM["ConversationManager"]:::core
        SM["SandboxManager"]:::core
        ExecS["ExecutionService"]:::core
        SpaceM["SpaceManager"]:::core
        TurnP["TurnPersistence"]:::core
        PathU["PathUtils"]:::core
        FileP["FilePreview"]:::core
        Coordinator["ExperimentCoordinator"]:::core
        Interfaces["Experiments Interfaces"]:::core
        Models["Experiments Models"]:::core
    end
    API --> PM
    API --> AM
    API --> CM
    API --> SM
    API --> ExecS
    click PM "https://github.com/neolaf2/society_zero_universe/blob/main/core/project_manager.py"
    click AM "https://github.com/neolaf2/society_zero_universe/blob/main/core/agent_manager.py"
    click CM "https://github.com/neolaf2/society_zero_universe/blob/main/core/conversation_manager.py"
    click SM "https://github.com/neolaf2/society_zero_universe/blob/main/core/sandbox_manager.py"
    click ExecS "https://github.com/neolaf2/society_zero_universe/blob/main/core/execution_service.py"
    click SpaceM "https://github.com/neolaf2/society_zero_universe/blob/main/core/space_manager.py"
    click TurnP "https://github.com/neolaf2/society_zero_universe/blob/main/core/turn_persistence.py"
    click PathU "https://github.com/neolaf2/society_zero_universe/blob/main/core/path_utils.py"
    click FileP "https://github.com/neolaf2/society_zero_universe/blob/main/core/file_preview.py"
    click Coordinator "https://github.com/neolaf2/society_zero_universe/blob/main/core/experiments/coordinator.py"
    click Interfaces "https://github.com/neolaf2/society_zero_universe/blob/main/core/experiments/interfaces.py"
    click Models "https://github.com/neolaf2/society_zero_universe/blob/main/core/experiments/models.py"

    %% Core Services
    subgraph "Core Services"
        ASS["AgentSetsService"]:::core
        EnvS["EnvironmentsService"]:::core
        EA["EnvironmentAssetsService"]:::core
        ENS["ExperimentNotebookService"]:::core
        EDAS["ExperimentDataAnalysisService"]:::core
        LS["LogicsService"]:::core
        MCS["ModelConfigurationService"]:::core
        SS["SchedulesService"]:::core
        SCS["ScheduleContextService"]:::core
        SOS["ScheduleOverviewService"]:::core
        SecS["SecretsService"]:::core
    end
    API --> ASS
    API --> EnvS
    API --> EA
    API --> ENS
    API --> EDAS
    API --> LS
    API --> MCS
    API --> SS
    API --> SCS
    API --> SOS
    API --> SecS
    click ASS "https://github.com/neolaf2/society_zero_universe/blob/main/core/services/agent_sets_service.py"
    click EnvS "https://github.com/neolaf2/society_zero_universe/blob/main/core/services/environments_service.py"
    click EA "https://github.com/neolaf2/society_zero_universe/blob/main/core/services/environment_assets_service.py"
    click ENS "https://github.com/neolaf2/society_zero_universe/blob/main/core/services/experiment_notebook_service.py"
    click EDAS "https://github.com/neolaf2/society_zero_universe/blob/main/core/services/experiment_data_analysis_service.py"
    click LS "https://github.com/neolaf2/society_zero_universe/blob/main/core/services/logics_service.py"
    click MCS "https://github.com/neolaf2/society_zero_universe/blob/main/core/services/model_configuration_service.py"
    click SS "https://github.com/neolaf2/society_zero_universe/blob/main/core/services/schedules_service.py"
    click SCS "https://github.com/neolaf2/society_zero_universe/blob/main/core/services/schedule_context_service.py"
    click SOS "https://github.com/neolaf2/society_zero_universe/blob/main/core/services/schedule_overview_service.py"
    click SecS "https://github.com/neolaf2/society_zero_universe/blob/main/core/services/secrets_service.py"

    %% Plugin Architecture
    subgraph "Plugins"
        RHandlers["Resource Handlers"]:::core
        WPlugins["Workflow Plugins"]:::core
    end
    RHandlers -->|uses| ASS
    RHandlers -->|uses| EnvS
    RHandlers -->|uses| LS
    click RHandlers "https://github.com/neolaf2/society_zero_universe/blob/main/core/plugins/resource/agent_set_handler.py"
    click RHandlers "https://github.com/neolaf2/society_zero_universe/blob/main/core/plugins/resource/environment_handler.py"
    click RHandlers "https://github.com/neolaf2/society_zero_universe/blob/main/core/plugins/resource/logic_handler.py"
    click RHandlers "https://github.com/neolaf2/society_zero_universe/blob/main/core/plugins/resource/schedule_handler.py"
    click RHandlers "https://github.com/neolaf2/society_zero_universe/blob/main/core/plugins/resource_plugin.py"
    click WPlugins "https://github.com/neolaf2/society_zero_universe/blob/main/core/plugins/workflows/create_experiment.yaml"
    click WPlugins "https://github.com/neolaf2/society_zero_universe/blob/main/core/plugins/guided_workflow_plugin.py"
    click WPlugins "https://github.com/neolaf2/society_zero_universe/blob/main/core/plugins/interactive_plugin.py"
    click WPlugins "https://github.com/neolaf2/society_zero_universe/blob/main/core/plugins/asset_listing_renderer.py"

    %% Libraries
    subgraph "Libraries"
        SimEngine["Simulation Engine"]:::lib
        AgentFw["Agent Framework"]:::lib
        DockerLib["Docker Sandbox Executor"]:::lib
    end
    Coordinator -->|"invoke"| SimEngine
    AM -->|"invoke"| AgentFw
    SM -->|"invoke"| DockerLib
    click SimEngine "https://github.com/neolaf2/society_zero_universe/tree/main/libs/simengine/src/simengine/"
    click AgentFw "https://github.com/neolaf2/society_zero_universe/blob/main/libs/agent/src/agent.py"
    click AgentFw "https://github.com/neolaf2/society_zero_universe/blob/main/libs/agent/src/agent_context.py"
    click AgentFw "https://github.com/neolaf2/society_zero_universe/blob/main/libs/agent/src/component_manager.py"
    click AgentFw "https://github.com/neolaf2/society_zero_universe/blob/main/libs/agent/src/llm.py"
    click AgentFw "https://github.com/neolaf2/society_zero_universe/blob/main/libs/agent/src/loop.py"
    click DockerLib "https://github.com/neolaf2/society_zero_universe/blob/main/libs/docker_sandbox/sandbox.py"

    %% External Systems
    subgraph "External Systems"
        DB["Database / File Store"]:::external
        LLM["LLM Providers"]:::external
        DockerDaemon["Docker Daemon"]:::external
        Scripts["Docker Build Scripts"]:::external
    end
    ESS["scripts/build_custom_image.sh"]
    Scripts --> DockerDaemon
    ExecS -->|"persist to DB"| DB
    ASS -->|"persist to DB"| DB
    AgentFw -->|"LLM API calls"| LLM
    DockerLib -->|"container run"| DockerDaemon
    click Scripts "https://github.com/neolaf2/society_zero_universe/blob/main/scripts/build_custom_image.sh"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#000
    classDef api fill:#E6FFEA,stroke:#28A745,color:#000
    classDef core fill:#FFF4E6,stroke:#FF8C00,color:#000
    classDef lib fill:#F3E8FF,stroke:#7A0BC0,color:#000
    classDef external fill:#E2E3E5,stroke:#6C757D,color:#000
```
