How neolaf2/society_zero_universe works
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)