# macaronquantum/ia-verse- architecture

> Architecture diagram of the GitHub repository macaronquantum/ia-verse-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/macaronquantum/ia-verse-
- Repository: https://github.com/macaronquantum/ia-verse-

## Overview

##### Repo purpose
This is a backend for a virtual economic world driven by autonomous AI agents. The core loop is a simulation tick: agents perceive the world, choose actions, create businesses, earn/spend money, and interact with bank/market systems. The repo also includes a separate API Gateway layer for tool execution and external integrations.

##### Primary runtime surfaces
The main application entrypoint is `app/main.py`, exposing a FastAPI REST API for world management and simulation control. A separate worker process (`run_worker.py`) handles background agent execution and scheduled work. The repository also ships a browser-based dashboard in `frontend/` and `web/`, typically served behind Nginx in Docker.

##### World simulation core
The simulation is organized around `app/simulation/`, `app/world/`, and `app/economy/`. These modules model world state, events, crises, production, markets, demand, reputation, and the simulation engine itself. The world tick is the central data flow: state advances, agents act, the economy updates, and downstream systems like banking, energy, and reputation are recalculated.

##### Autonomous agent subsystem
Agent behavior lives under `app/agents/`. This includes decision-making, planning, memory, personality, goals, scheduler, resource optimization, evolution, and worker pool orchestration. Agents appear to be built as composable decision systems rather than a single monolith: a factory creates agents, a loop executes them, and specialized components handle memory, strategy, tool selection, and execution.

##### Business and organization layer
`app/business/`, `app/companies`-like logic via the API, `app/organizations/`, `app/institutions/`, and `app/humans/` model enterprises, jobs, task dispatching, and organizational entities. This layer connects agent activity to economic output: agents can found businesses, acquire inputs, produce goods, and sell through market mechanisms. The readme’s “startup evolution” and opportunity engines indicate a startup/business lifecycle on top of the base simulation.

##### Banking, wallets, and crypto settlement
Financial infrastructure is spread across `app/crypto/`, `app/wallets/`, `app/storage/database.py`, and integration clients for Solana/Stripe/Coinbase-style flows. The system supports encrypted wallet lifecycle, balance checks, transactions, and settlement flows. This matters architecturally because the simulation’s “energy core” is tied to real or simulated monetary balance, so wallet/bank state is a first-class dependency of agent survival.

##### API Gateway v10 as a separate boundary
`app/api_gateway/` is its own subsystem with service registry, cost estimation, tool calling, and sandboxed execution. It has dedicated sandbox runners for Docker and WASM, plus adapters to tool manifests and external dependencies. This is a clear boundary between “simulation/world APIs” and “tool execution APIs”: the gateway governs what tools exist, how they are priced, and how they are safely executed.

##### Tooling and external integrations
`app/tools/`, `app/integrations/`, `app/external/`, and `app/web/` support real-world actions such as browser automation, scraping, social posting, cloud services, messaging, and payment providers. The integration layer is intentionally adapter-based, so external services are isolated behind client modules and tool manifests. This is likely where the system crosses from simulated economy into real APIs.

##### Memory, sensing, and data ingestion
Agent/world perception is fed by `app/sensing/` streams, `app/data/market_intelligence.py`, and memory stores in `app/memory/`. Persistent episodic/vector memory and market/news/social/web trend streams provide inputs to agent reasoning and opportunity discovery. Architecturally, this is the ingestion and context layer that transforms external signals into decision-making inputs.

##### LLM and local model runtime
`app/llm/` contains local model management and provider adapters, including vLLM-style runtime support. The repo is designed for hybrid execution: some decisions can be made locally, some can route externally, and GPU deployment is supported via the Docker/GPU compose setup. This layer is important because it provides the reasoning backend for agents and tool orchestration.

##### Persistence and schema management
Data persistence is handled through `app/persistence/`, `app/db/`, `app/storage/`, and migrations in both Alembic and SQL migration directories. PostgreSQL is the primary durable store, with Redis used for runtime coordination in the Docker deployment. This gives the system two important state boundaries: long-lived simulation data in Postgres and transient coordination/cache in Redis.

##### Security, compliance, and auditability
`app/security/`, `app/justice/`, `app/compliance`, tamper logs, and quota/reputation tests indicate an explicit governance layer. The gateway adds RBAC-style headers, quota enforcement, reputation penalties, and tamper-evident usage logs. This is not just an app concern; it is part of the architecture because agent/tool execution is controlled through policy, auditing, and sandboxing.

##### Deployment topology
The default deployment is containerized: API, frontend, workers, Redis, and PostgreSQL are brought up together via Docker Compose. GPU-specific deployment swaps in model-serving support, while scripts under `scripts/` cover gateway startup, simulation runs, model downloads, and environment bootstrap. This repo therefore has a multi-process architecture with explicit separation between HTTP serving, background simulation workers, state storage, and model execution.

Main entry points: [`app/api_gateway`](https://github.com/macaronquantum/ia-verse-/tree/main/app/api_gateway) (Gateway), [`app/agents`](https://github.com/macaronquantum/ia-verse-/tree/main/app/agents) (Agents), [`app/main.py`](https://github.com/macaronquantum/ia-verse-/blob/main/app/main.py) (Main API), [`app/simulation`](https://github.com/macaronquantum/ia-verse-/tree/main/app/simulation) (Simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime surfaces"]
  node_frontend["Frontend<br/>dashboard UI"]
  node_web["Web shell<br/>nginx site"]
  node_main_api["Main API<br/>FastAPI app<br/>[main.py]"]
  node_worker["Worker<br/>background runner<br/>[run_worker.py]"]
end

subgraph group_core["Simulation core"]
  node_simulation{{"Simulation<br/>tick engine"}}
  node_world["World state<br/>state + events"]
  node_agents{{"Agents"}}
  node_economy{{"Economy<br/>economic model"}}
  node_business{{"Business<br/>venture layer"}}
  node_organizations["Organizations<br/>org system"]
end

subgraph group_gateway["API gateway"]
  node_api_gateway{{"Gateway<br/>tool boundary"}}
  node_registry["Registry<br/>tool catalog<br/>[registry.py]"]
  node_sandbox{{"Sandbox<br/>execution runners"}}
  node_tools["Tools<br/>tool adapters"]
end

subgraph group_platform["Platform services"]
  node_integrations["Integrations<br/>external clients"]
  node_storage[("Storage<br/>persistence")]
  node_security{{"Security<br/>policy layer"}}
  node_observability(("Observability<br/>metrics"))
end

node_frontend -->|"control"| node_main_api
node_web -->|"serve"| node_frontend
node_main_api -->|"tick control"| node_simulation
node_worker -->|"run"| node_agents
node_simulation -->|"advance"| node_world
node_simulation -->|"orchestrate"| node_agents
node_agents -->|"act on"| node_economy
node_agents -->|"found"| node_business
node_business -->|"produce"| node_economy
node_economy -->|"recalculate"| node_world
node_organizations -->|"host"| node_business
node_main_api -->|"persist"| node_storage
node_simulation -->|"store"| node_storage
node_agents -->|"govern"| node_security
node_main_api -->|"emit"| node_observability
node_api_gateway -->|"resolve"| node_registry
node_api_gateway -->|"execute"| node_sandbox
node_api_gateway -->|"adapt"| node_tools
node_tools -->|"call out"| node_integrations
node_api_gateway -->|"enforce"| node_security
node_api_gateway -->|"record"| node_storage

click node_frontend "https://github.com/macaronquantum/ia-verse-/tree/main/frontend"
click node_web "https://github.com/macaronquantum/ia-verse-/tree/main/web"
click node_main_api "https://github.com/macaronquantum/ia-verse-/blob/main/app/main.py"
click node_worker "https://github.com/macaronquantum/ia-verse-/blob/main/run_worker.py"
click node_simulation "https://github.com/macaronquantum/ia-verse-/tree/main/app/simulation"
click node_world "https://github.com/macaronquantum/ia-verse-/tree/main/app/world"
click node_agents "https://github.com/macaronquantum/ia-verse-/tree/main/app/agents"
click node_economy "https://github.com/macaronquantum/ia-verse-/tree/main/app/economy"
click node_business "https://github.com/macaronquantum/ia-verse-/tree/main/app/business"
click node_organizations "https://github.com/macaronquantum/ia-verse-/tree/main/app/organizations"
click node_api_gateway "https://github.com/macaronquantum/ia-verse-/tree/main/app/api_gateway"
click node_registry "https://github.com/macaronquantum/ia-verse-/blob/main/app/api_gateway/registry.py"
click node_sandbox "https://github.com/macaronquantum/ia-verse-/tree/main/app/api_gateway/sandbox"
click node_tools "https://github.com/macaronquantum/ia-verse-/tree/main/app/api_gateway/tools"
click node_integrations "https://github.com/macaronquantum/ia-verse-/tree/main/app/integrations"
click node_storage "https://github.com/macaronquantum/ia-verse-/tree/main/app/storage"
click node_security "https://github.com/macaronquantum/ia-verse-/tree/main/app/security"
click node_observability "https://github.com/macaronquantum/ia-verse-/tree/main/app/observability"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_web,node_main_api,node_worker toneBlue
class node_simulation,node_world,node_agents,node_economy,node_business,node_organizations toneAmber
class node_api_gateway,node_registry,node_sandbox,node_tools toneMint
class node_integrations,node_storage,node_security,node_observability toneRose
```

## Components

### Runtime surfaces

HTTP API, worker, and UI entrypoints

- [Frontend](https://github.com/macaronquantum/ia-verse-/tree/main/frontend): dashboard UI · Browser dashboard and marketplace UI · `frontend`
- [Web shell](https://github.com/macaronquantum/ia-verse-/tree/main/web): nginx site · Containerized web front-end and reverse proxy · `web`
- [Main API](https://github.com/macaronquantum/ia-verse-/blob/main/app/main.py): FastAPI app · Primary HTTP surface for world management and simulation control · `app/main.py`
- [Worker](https://github.com/macaronquantum/ia-verse-/blob/main/run_worker.py): background runner · Background agent execution and scheduled work · `run_worker.py`

### Simulation core

World, agents, economy, and business systems

- [Simulation](https://github.com/macaronquantum/ia-verse-/tree/main/app/simulation): tick engine · Advances the world tick and coordinates simulation flow · `app/simulation`
- [World state](https://github.com/macaronquantum/ia-verse-/tree/main/app/world): state + events · World state, crises, and event lifecycle · `app/world`
- [Agents](https://github.com/macaronquantum/ia-verse-/tree/main/app/agents): autonomous agents · Decision, memory, planning, scheduling, and execution systems · `app/agents`
- [Economy](https://github.com/macaronquantum/ia-verse-/tree/main/app/economy): economic model · Markets, demand, production, reputation, and central bank · `app/economy`
- [Business](https://github.com/macaronquantum/ia-verse-/tree/main/app/business): venture layer · Opportunity discovery, startup evolution, and business metrics · `app/business`
- [Organizations](https://github.com/macaronquantum/ia-verse-/tree/main/app/organizations): org system · Institutional and organizational entities tied to the simulation · `app/organizations`

### API gateway

Tool registry, pricing, sandbox, and external tool execution

- [Gateway](https://github.com/macaronquantum/ia-verse-/tree/main/app/api_gateway): tool boundary · Separate boundary for tool execution, costing, and policy · `app/api_gateway`
- [Registry](https://github.com/macaronquantum/ia-verse-/blob/main/app/api_gateway/registry.py): tool catalog · Tool registry and service discovery for gateway execution · `app/api_gateway/registry.py`
- [Sandbox](https://github.com/macaronquantum/ia-verse-/tree/main/app/api_gateway/sandbox): execution runners · Isolated Docker and WASM tool runners · `app/api_gateway/sandbox`
- [Tools](https://github.com/macaronquantum/ia-verse-/tree/main/app/api_gateway/tools): tool adapters · Manifest-backed tools and adapter layer · `app/api_gateway/tools`

### Platform services

Persistence, security, observability, and integrations

- [Integrations](https://github.com/macaronquantum/ia-verse-/tree/main/app/integrations): external clients · Third-party service clients and settlement adapters · `app/integrations`
- [Storage](https://github.com/macaronquantum/ia-verse-/tree/main/app/storage): persistence · Database, durable store, and migration-backed state · `app/storage`
- [Security](https://github.com/macaronquantum/ia-verse-/tree/main/app/security): policy layer · Permissions, tamper logging, and governance controls · `app/security`
- [Observability](https://github.com/macaronquantum/ia-verse-/tree/main/app/observability): metrics · Monitoring and metrics collection for runtime health · `app/observability`

## Connections

- Frontend → Main API: control · Dashboard drives world and simulation actions
- Web shell → Frontend: serve · Nginx serves the browser application
- Main API → Simulation: tick control · API starts, stops, and inspects simulation flow
- Worker → Agents: run · Background execution processes agent workloads
- Simulation → World state: advance · Tick updates world state and events
- Simulation → Agents: orchestrate · Simulation coordinates agent decisions and actions
- Agents → Economy: act on · Agent actions affect markets, demand, and production
- Agents → Business: found · Agents create and evolve businesses
- Business → Economy: produce · Business output feeds the economic system
- Economy → World state: recalculate · Economic state feeds back into the world tick
- Organizations → Business: host · Organizations provide structure for enterprises and jobs
- Main API → Storage: persist · HTTP state changes are written durably
- Simulation → Storage: store · Simulation snapshots and state are persisted
- Agents → Security: govern · Agent/tool activity is constrained by policy
- Main API → Observability: emit · Operational and simulation metrics are exposed
- Gateway → Registry: resolve · Gateway looks up available tools and services
- Gateway → Sandbox: execute · Tool calls run inside isolated sandboxes
- Gateway → Tools: adapt · Manifests are translated into executable tools
- Tools → Integrations: call out · Tools delegate to external service clients
- Gateway → Security: enforce · Gateway applies access control and tamper logging
- Gateway → Storage: record · Gateway usage and billing state are persisted
