# trossini02/aisland architecture

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

- Interactive diagram: https://gitdiagram.com/trossini02/aisland
- Repository: https://github.com/trossini02/aisland

## Overview

AIsland is a desktop lab for running one to ten AI agents in a configurable island simulation, watching their activity, and analyzing results. The main workflow runs from setup and model selection through simulation and live viewing to reports and run comparisons. The graph captures the documented workflow and sampled module relationships; several subsystems are represented by their exact source directories because their implementation files were not sampled.

Main entry points: [`src/run/controller.ts`](https://github.com/trossini02/aisland/blob/main/src/run/controller.ts) (Run controller), [`src/renderer/src/App.tsx`](https://github.com/trossini02/aisland/blob/main/src/renderer/src/App.tsx) (App screens), [`src/main/runs.ts`](https://github.com/trossini02/aisland/blob/main/src/main/runs.ts) (Run service), [`src/agents/mind.ts`](https://github.com/trossini02/aisland/blob/main/src/agents/mind.ts) (Agent mind)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_app["App screens<br/>[App.tsx]"]
  node_setup["Run setup<br/>[NewRun.tsx]"]
  node_live["Live island<br/>[Live.tsx]"]
  node_reportscreen["Report and compare<br/>[Report.tsx]"]
  node_bridge["Desktop IPC<br/>[ipc.ts]"]
end

subgraph group_run["Run orchestration"]
  node_mainruns["Run service<br/>[runs.ts]"]
  node_controller["Run controller<br/>[controller.ts]"]
  node_config["Run configuration<br/>[config.ts]"]
end

subgraph group_agents["Agent cognition"]
  node_mind["Agent mind<br/>[mind.ts]"]
  node_decision["Decision parsing<br/>[decision.ts]"]
  node_providers["Model providers"]
end

subgraph group_simulation["Island simulation"]
  node_world["World state<br/>[world.ts]"]
  node_worldgen["World generation"]
  node_tools["Agent tools"]
  node_laws["Laws and homes"]
end

subgraph group_analysis["Run analysis"]
  node_store[("Run storage<br/>[store.ts]")]
  node_reports["Report analysis<br/>[tables.ts]"]
  node_sharedreport["Report schema<br/>[report.ts]"]
  node_viewer["Browser replay<br/>[IslandReplay.tsx]"]
end

node_owner(("Run owner"))

node_owner -->|"uses"| node_app
node_app -->|"opens setup"| node_setup
node_app -->|"opens live"| node_live
node_app -->|"opens reports"| node_reportscreen
node_owner -->|"configures run"| node_setup
node_setup -.->|"sends run settings"| node_bridge
node_bridge -.->|"dispatches requests"| node_mainruns
node_mainruns -->|"starts runs"| node_controller
node_mainruns -->|"selects providers"| node_providers
node_controller -->|"generates island"| node_worldgen
node_controller -->|"creates world"| node_world
node_controller -->|"requests decisions"| node_mind
node_mind -->|"parses decisions"| node_decision
node_decision -->|"queues actions"| node_tools
node_mind -.->|"requests model output"| node_providers
node_owner -->|"chooses model"| node_providers
node_owner -->|"watches activity"| node_live
node_controller -.->|"persists run data"| node_store
node_owner -->|"studies results"| node_reportscreen
node_reportscreen -.->|"requests run results"| node_bridge
node_reports -->|"reads run data"| node_store
node_reports -->|"builds report"| node_sharedreport
node_owner -->|"views replay"| node_viewer
node_world -.->|"applies world rules"| node_laws

click node_app "https://github.com/trossini02/aisland/blob/main/src/renderer/src/App.tsx"
click node_setup "https://github.com/trossini02/aisland/blob/main/src/renderer/src/screens/NewRun.tsx"
click node_live "https://github.com/trossini02/aisland/blob/main/src/renderer/src/screens/Live.tsx"
click node_reportscreen "https://github.com/trossini02/aisland/blob/main/src/renderer/src/screens/Report.tsx"
click node_bridge "https://github.com/trossini02/aisland/blob/main/src/shared/ipc.ts"
click node_mainruns "https://github.com/trossini02/aisland/blob/main/src/main/runs.ts"
click node_controller "https://github.com/trossini02/aisland/blob/main/src/run/controller.ts"
click node_config "https://github.com/trossini02/aisland/blob/main/src/shared/config.ts"
click node_mind "https://github.com/trossini02/aisland/blob/main/src/agents/mind.ts"
click node_decision "https://github.com/trossini02/aisland/blob/main/src/agents/decision.ts"
click node_providers "https://github.com/trossini02/aisland/tree/main/src/agents/providers"
click node_world "https://github.com/trossini02/aisland/blob/main/src/sim/world.ts"
click node_worldgen "https://github.com/trossini02/aisland/tree/main/src/sim/worldgen"
click node_tools "https://github.com/trossini02/aisland/tree/main/src/sim/tools"
click node_laws "https://github.com/trossini02/aisland/tree/main/src/sim/law"
click node_store "https://github.com/trossini02/aisland/blob/main/src/run/store.ts"
click node_reports "https://github.com/trossini02/aisland/blob/main/src/run/tables.ts"
click node_sharedreport "https://github.com/trossini02/aisland/blob/main/src/shared/report.ts"
click node_viewer "https://github.com/trossini02/aisland/blob/main/viewer/src/IslandReplay.tsx"

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_app,node_setup,node_live,node_reportscreen,node_bridge toneBlue
class node_mainruns,node_controller,node_config toneAmber
class node_mind,node_decision,node_providers toneMint
class node_world,node_worldgen,node_tools,node_laws toneRose
class node_store,node_reports,node_sharedreport,node_viewer,node_owner toneIndigo
```

## Components

### Desktop app

- [App screens](https://github.com/trossini02/aisland/blob/main/src/renderer/src/App.tsx): `src/renderer/src/App.tsx`
- [Run setup](https://github.com/trossini02/aisland/blob/main/src/renderer/src/screens/NewRun.tsx): `src/renderer/src/screens/NewRun.tsx`
- [Live island](https://github.com/trossini02/aisland/blob/main/src/renderer/src/screens/Live.tsx): `src/renderer/src/screens/Live.tsx`
- [Report and compare](https://github.com/trossini02/aisland/blob/main/src/renderer/src/screens/Report.tsx): `src/renderer/src/screens/Report.tsx`
- [Desktop IPC](https://github.com/trossini02/aisland/blob/main/src/shared/ipc.ts): `src/shared/ipc.ts`

### Run orchestration

- [Run service](https://github.com/trossini02/aisland/blob/main/src/main/runs.ts): `src/main/runs.ts`
- [Run controller](https://github.com/trossini02/aisland/blob/main/src/run/controller.ts): `src/run/controller.ts`
- [Run configuration](https://github.com/trossini02/aisland/blob/main/src/shared/config.ts): `src/shared/config.ts`

### Agent cognition

- [Agent mind](https://github.com/trossini02/aisland/blob/main/src/agents/mind.ts): `src/agents/mind.ts`
- [Decision parsing](https://github.com/trossini02/aisland/blob/main/src/agents/decision.ts): `src/agents/decision.ts`
- [Model providers](https://github.com/trossini02/aisland/tree/main/src/agents/providers): `src/agents/providers`

### Island simulation

- [World state](https://github.com/trossini02/aisland/blob/main/src/sim/world.ts): `src/sim/world.ts`
- [World generation](https://github.com/trossini02/aisland/tree/main/src/sim/worldgen): `src/sim/worldgen`
- [Agent tools](https://github.com/trossini02/aisland/tree/main/src/sim/tools): `src/sim/tools`
- [Laws and homes](https://github.com/trossini02/aisland/tree/main/src/sim/law): `src/sim/law`

### Run analysis

- [Run storage](https://github.com/trossini02/aisland/blob/main/src/run/store.ts): `src/run/store.ts`
- [Report analysis](https://github.com/trossini02/aisland/blob/main/src/run/tables.ts): `src/run/tables.ts`
- [Report schema](https://github.com/trossini02/aisland/blob/main/src/shared/report.ts): `src/shared/report.ts`
- [Browser replay](https://github.com/trossini02/aisland/blob/main/viewer/src/IslandReplay.tsx): `viewer/src/IslandReplay.tsx`

### Other components

- **Run owner**

## Connections

- Run owner → App screens: uses (evidence: `README.md`)
- App screens → Run setup: opens setup (evidence: `src/renderer/src/App.tsx`)
- App screens → Live island: opens live (evidence: `src/renderer/src/App.tsx`)
- App screens → Report and compare: opens reports (evidence: `src/renderer/src/App.tsx`)
- Run owner → Run setup: configures run (evidence: `README.md`)
- Run setup → Desktop IPC: sends run settings
- Desktop IPC → Run service: dispatches requests (evidence: `src/main/runs.ts`)
- Run service → Run controller: starts runs (evidence: `src/main/runs.ts`)
- Run service → Model providers: selects providers (evidence: `src/main/runs.ts`)
- Run controller → World generation: generates island (evidence: `src/run/controller.ts`)
- Run controller → World state: creates world (evidence: `src/run/controller.ts`)
- Run controller → Agent mind: requests decisions (evidence: `src/run/controller.ts`)
- Agent mind → Decision parsing: parses decisions (evidence: `src/agents/mind.ts`)
- Decision parsing → Agent tools: queues actions (evidence: `src/agents/decision.ts`)
- Agent mind → Model providers: requests model output (evidence: `src/agents/mind.ts`)
- Run owner → Model providers: chooses model (evidence: `README.md`)
- Run owner → Live island: watches activity (evidence: `README.md`)
- Run controller → Run storage: persists run data
- Run owner → Report and compare: studies results (evidence: `README.md`)
- Report and compare → Desktop IPC: requests run results
- Report analysis → Run storage: reads run data (evidence: `src/run/tables.ts`)
- Report analysis → Report schema: builds report (evidence: `src/run/tables.ts`)
- Run owner → Browser replay: views replay (evidence: `README.md`)
- World state → Laws and homes: applies world rules (evidence: `src/sim/law/homes.ts`)
