# rojld/agagi architecture

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

- Interactive diagram: https://gitdiagram.com/rojld/agagi
- Repository: https://github.com/rojld/agagi

## Overview

AGAGI is an empirical agent-and-world simulation research platform: researchers run evolutionary experiments in demanding simulated environments, assess whether cognition improves outcomes, and preserve findings as decision records and run data. Its dashboard exposes runs, comparisons, live activity, provenance, and the research record. The graph combines documented research capabilities with relationships visible in sampled source; several dashboard and backend subsystems are represented from the tree and README, so their internal wiring is not inferred.

Main entry points: [`src/environments/biosphere.py`](https://github.com/rojld/agagi/blob/main/src/environments/biosphere.py) (Biosphere simulation), [`backend/app/main.py`](https://github.com/rojld/agagi/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/routes`](https://github.com/rojld/agagi/tree/main/backend/app/routes) (Product API routes), [`backend/app/services/data_service.py`](https://github.com/rojld/agagi/blob/main/backend/app/services/data_service.py) (Experiment data service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_research["Research workflow"]
  node_research_gates["Research gates"]
  node_preflight["Experiment preflight"]
  node_run_entry["Experiment runner<br/>[main_biosphere.py]"]
end

subgraph group_simulation["Agents and worlds"]
  node_agent["Mamba agent<br/>[mamba_agent.py]"]
  node_world["Stoneage world"]
  node_environment["Environment systems"]
  node_biosphere["Biosphere simulation<br/>[biosphere.py]"]
end

subgraph group_evolution["Evolution and records"]
  node_evolution["Evolution engine<br/>[evolution.py]"]
  node_mutation["Genome mutation<br/>[mutation.py]"]
  node_persistence["Agent persistence<br/>[persistence.py]"]
  node_experiment_logging["Experiment logging<br/>[async_logger.py]"]
  node_experiment_tracking["Experiment tracking"]
  node_decision_records[("Decision record graph<br/>[database.py]")]
  node_visualization["Experiment visualization<br/>[visualization.py]"]
end

subgraph group_backend["API and services"]
  node_api["FastAPI application<br/>[main.py]"]
  node_routes["Product API routes"]
  node_data_service["Experiment data service<br/>[data_service.py]"]
  node_runs_service["Run services<br/>[runs_service.py]"]
end

subgraph group_frontend["Research dashboard"]
  node_dashboard["Research dashboard<br/>[App.tsx]"]
  node_dashboard_views["Research views"]
  node_api_client["Dashboard API client<br/>[client.ts]"]
end

node_researcher(("Researcher"))

node_researcher -->|"checks design"| node_preflight
node_researcher -.->|"starts experiments"| node_run_entry
node_research_gates -->|"sets criteria"| node_preflight
node_run_entry -.->|"runs simulation"| node_biosphere
node_biosphere -->|"mutates genomes"| node_mutation
node_biosphere -->|"persists agents"| node_persistence
node_evolution -->|"applies mutations"| node_mutation
node_world -->|"uses systems"| node_environment
node_world -.->|"evaluates agents"| node_agent
node_biosphere -->|"simulates agents"| node_agent
node_experiment_logging -->|"logs experiments"| node_experiment_tracking
node_researcher -->|"inspects findings"| node_dashboard
node_dashboard -->|"renders views"| node_dashboard_views
node_dashboard_views -.->|"requests data"| node_api_client
node_api_client -.->|"calls API"| node_api
node_api -->|"mounts routers"| node_routes
node_api -->|"configures service"| node_data_service
node_routes -->|"reads experiment data"| node_data_service
node_routes -.->|"serves run operations"| node_runs_service
node_data_service -->|"reads experiment records"| node_experiment_logging
node_decision_records -->|"stores decisions"| node_research_gates
node_researcher -->|"curates conclusions"| node_decision_records

click node_preflight "https://github.com/rojld/agagi/blob/main/tools/experiment_preflight.py"
click node_agent "https://github.com/rojld/agagi/blob/main/src/agents/mamba_agent.py"
click node_world "https://github.com/rojld/agagi/blob/main/src/worlds/world_1_stoneage.py"
click node_environment "https://github.com/rojld/agagi/tree/main/src/environments"
click node_biosphere "https://github.com/rojld/agagi/blob/main/src/environments/biosphere.py"
click node_evolution "https://github.com/rojld/agagi/blob/main/src/seed_ai/evolution.py"
click node_mutation "https://github.com/rojld/agagi/blob/main/src/seed_ai/mutation.py"
click node_persistence "https://github.com/rojld/agagi/blob/main/src/seed_ai/persistence.py"
click node_experiment_logging "https://github.com/rojld/agagi/blob/main/src/graph_rag/async_logger.py"
click node_experiment_tracking "https://github.com/rojld/agagi/blob/main/src/graph_rag/experiment_tracker.py"
click node_decision_records "https://github.com/rojld/agagi/blob/main/src/graph_rag/database.py"
click node_visualization "https://github.com/rojld/agagi/blob/main/src/visualization.py"
click node_api "https://github.com/rojld/agagi/blob/main/backend/app/main.py"
click node_routes "https://github.com/rojld/agagi/tree/main/backend/app/routes"
click node_data_service "https://github.com/rojld/agagi/blob/main/backend/app/services/data_service.py"
click node_runs_service "https://github.com/rojld/agagi/blob/main/backend/app/services/runs_service.py"
click node_dashboard "https://github.com/rojld/agagi/blob/main/frontend/src/App.tsx"
click node_dashboard_views "https://github.com/rojld/agagi/tree/main/frontend/src/components"
click node_api_client "https://github.com/rojld/agagi/blob/main/frontend/src/api/client.ts"
click node_run_entry "https://github.com/rojld/agagi/blob/main/main_biosphere.py"

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_research_gates,node_preflight,node_run_entry toneBlue
class node_agent,node_world,node_environment,node_biosphere toneAmber
class node_evolution,node_mutation,node_persistence,node_experiment_logging,node_experiment_tracking,node_decision_records,node_visualization toneMint
class node_api,node_routes,node_data_service,node_runs_service toneRose
class node_dashboard,node_dashboard_views,node_api_client,node_researcher toneIndigo
```

## Components

### Research workflow

- **Research gates**
- [Experiment preflight](https://github.com/rojld/agagi/blob/main/tools/experiment_preflight.py): `tools/experiment_preflight.py`
- [Experiment runner](https://github.com/rojld/agagi/blob/main/main_biosphere.py): `main_biosphere.py`

### Agents and worlds

- [Mamba agent](https://github.com/rojld/agagi/blob/main/src/agents/mamba_agent.py): `src/agents/mamba_agent.py`
- [Stoneage world](https://github.com/rojld/agagi/blob/main/src/worlds/world_1_stoneage.py): `src/worlds/world_1_stoneage.py`
- [Environment systems](https://github.com/rojld/agagi/tree/main/src/environments): `src/environments`
- [Biosphere simulation](https://github.com/rojld/agagi/blob/main/src/environments/biosphere.py): `src/environments/biosphere.py`

### Evolution and records

- [Evolution engine](https://github.com/rojld/agagi/blob/main/src/seed_ai/evolution.py): `src/seed_ai/evolution.py`
- [Genome mutation](https://github.com/rojld/agagi/blob/main/src/seed_ai/mutation.py): `src/seed_ai/mutation.py`
- [Agent persistence](https://github.com/rojld/agagi/blob/main/src/seed_ai/persistence.py): `src/seed_ai/persistence.py`
- [Experiment logging](https://github.com/rojld/agagi/blob/main/src/graph_rag/async_logger.py): `src/graph_rag/async_logger.py`
- [Experiment tracking](https://github.com/rojld/agagi/blob/main/src/graph_rag/experiment_tracker.py): `src/graph_rag/experiment_tracker.py`
- [Decision record graph](https://github.com/rojld/agagi/blob/main/src/graph_rag/database.py): `src/graph_rag/database.py`
- [Experiment visualization](https://github.com/rojld/agagi/blob/main/src/visualization.py): `src/visualization.py`

### API and services

- [FastAPI application](https://github.com/rojld/agagi/blob/main/backend/app/main.py): `backend/app/main.py`
- [Product API routes](https://github.com/rojld/agagi/tree/main/backend/app/routes): `backend/app/routes`
- [Experiment data service](https://github.com/rojld/agagi/blob/main/backend/app/services/data_service.py): `backend/app/services/data_service.py`
- [Run services](https://github.com/rojld/agagi/blob/main/backend/app/services/runs_service.py): `backend/app/services/runs_service.py`

### Research dashboard

- [Research dashboard](https://github.com/rojld/agagi/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Research views](https://github.com/rojld/agagi/tree/main/frontend/src/components): `frontend/src/components`
- [Dashboard API client](https://github.com/rojld/agagi/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Other components

- **Researcher**

## Connections

- Researcher → Experiment preflight: checks design (evidence: `README.md`)
- Researcher → Experiment runner: starts experiments
- Research gates → Experiment preflight: sets criteria (evidence: `README.md`)
- Experiment runner → Biosphere simulation: runs simulation
- Biosphere simulation → Genome mutation: mutates genomes (evidence: `src/environments/biosphere.py`)
- Biosphere simulation → Agent persistence: persists agents (evidence: `src/environments/biosphere.py`)
- Evolution engine → Genome mutation: applies mutations (evidence: `src/seed_ai/evolution.py`)
- Stoneage world → Environment systems: uses systems (evidence: `src/worlds/world_1_stoneage.py`)
- Stoneage world → Mamba agent: evaluates agents (evidence: `src/worlds/world_1_stoneage.py`)
- Biosphere simulation → Mamba agent: simulates agents (evidence: `src/environments/biosphere.py`)
- Experiment logging → Experiment tracking: logs experiments (evidence: `src/graph_rag/async_logger.py`)
- Researcher → Research dashboard: inspects findings (evidence: `README.md`)
- Research dashboard → Research views: renders views (evidence: `frontend/src/App.tsx`)
- Research views → Dashboard API client: requests data (evidence: `frontend/src/components/ForageFunnelView.tsx`)
- Dashboard API client → FastAPI application: calls API
- FastAPI application → Product API routes: mounts routers (evidence: `backend/app/main.py`)
- FastAPI application → Experiment data service: configures service (evidence: `backend/app/main.py`)
- Product API routes → Experiment data service: reads experiment data (evidence: `backend/app/routes/academy.py`)
- Product API routes → Run services: serves run operations
- Experiment data service → Experiment logging: reads experiment records (evidence: `backend/app/services/data_service.py`)
- Decision record graph → Research gates: stores decisions (evidence: `README.md`)
- Researcher → Decision record graph: curates conclusions (evidence: `README.md`)
