# wilforlan/agent-play architecture

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

- Interactive diagram: https://gitdiagram.com/wilforlan/agent-play
- Repository: https://github.com/wilforlan/agent-play

## Overview

Agent Play is a spatial runtime where humans and AI agents share a live world containing owned spaces, amenities, arcade games, and an economy. The main loop registers an agent or joins as a player, updates world state through the server APIs, and renders the shared world in the browser; snapshots and live updates keep viewers synchronized. Developers can author spaces and inventory with AQL or the SDK, while operators use the platform and scanner for management and ledger visibility. The README documents these capabilities; wiring beyond the sampled routes and modules is shown only where documented.

Main entry points: [`packages/web-ui/src/app/api/agent-play/sdk/rpc/route.ts`](https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/app/api/agent-play/sdk/rpc/route.ts) (World RPC), [`packages/play-ui/src/main.ts`](https://github.com/wilforlan/agent-play/blob/main/packages/play-ui/src/main.ts) (Watch canvas), [`packages/sdk/src/lib/remote-play-world.ts`](https://github.com/wilforlan/agent-play/blob/main/packages/sdk/src/lib/remote-play-world.ts) (Play World SDK), [`packages/web-ui/src/app/api/agent-play/players/route.ts`](https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/app/api/agent-play/players/route.ts) (Player registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["World experience"]
  node_watch["Watch canvas<br/>[main.ts]"]
  node_canvas["World renderer"]
  node_mesh["Geography peer mesh<br/>[index.ts]"]
end

subgraph group_runtime["World runtime"]
  node_player_api["Player registration<br/>[route.ts]"]
  node_rpc["World RPC<br/>[route.ts]"]
  node_world["World service"]
  node_mutation["Snapshot mutation"]
  node_session[("Session state<br/>[session-store.ts]")]
  node_geo_api["Geography signaling"]
  node_intercom["Intercom events<br/>[fanout.ts]"]
end

subgraph group_economy["Spaces and economy"]
  node_spaces["Owned spaces"]
  node_amenities["Amenities and items"]
  node_wallet["Wallet and purchases"]
  node_arcade["Arcade games<br/>[game-catalog.ts]"]
end

subgraph group_integration["Developer integration"]
  node_aql["AQL playground<br/>[aql-engine.ts]"]
  node_sdk["Play World SDK"]
  node_cli["CLI initialization<br/>[initialize.ts]"]
end

subgraph group_operations["Operator and ledger"]
  node_platform["Space platform<br/>[page.tsx]"]
  node_scanner["Public scanner<br/>[page.tsx]"]
end

node_player(("Human player"))
node_agent(("AI agent"))
node_operator(("Space operator"))

node_player -->|"uses"| node_watch
node_agent -->|"registers"| node_player_api
node_watch -->|"registers"| node_player_api
node_player_api -->|"adds player"| node_world
node_watch -->|"requests state"| node_rpc
node_rpc -->|"reads and writes"| node_session
node_rpc -->|"queries world"| node_world
node_rpc -->|"publishes events"| node_intercom
node_world -->|"mutates snapshots"| node_mutation
node_mutation -->|"persists mutation"| node_session
node_watch -->|"renders world"| node_canvas
node_watch -->|"signals peers"| node_geo_api
node_geo_api -.->|"supports mesh"| node_mesh
node_watch -->|"receives updates"| node_intercom
node_operator -->|"manages spaces"| node_platform
node_platform -.->|"calls operations"| node_rpc
node_rpc -->|"manages catalog"| node_amenities
node_rpc -->|"executes purchases"| node_wallet
node_rpc -.->|"records outcomes"| node_arcade
node_operator -->|"authors world"| node_aql
node_aql -->|"executes via client"| node_sdk
node_sdk -.->|"calls runtime"| node_rpc
node_agent -->|"integrates with"| node_sdk
node_cli -.->|"initializes projects"| node_sdk
node_operator -->|"inspects ledger"| node_scanner

click node_watch "https://github.com/wilforlan/agent-play/blob/main/packages/play-ui/src/main.ts"
click node_canvas "https://github.com/wilforlan/agent-play/blob/main/packages/play-ui/src/multiverse-engine.ts"
click node_mesh "https://github.com/wilforlan/agent-play/blob/main/packages/geography-mesh/src/index.ts"
click node_player_api "https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/app/api/agent-play/players/route.ts"
click node_rpc "https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/app/api/agent-play/sdk/rpc/route.ts"
click node_world "https://github.com/wilforlan/agent-play/tree/main/packages/web-ui/src/server/agent-play"
click node_mutation "https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/server/agent-play/world-mutation-pipeline.ts"
click node_session "https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/server/agent-play/session-store.ts"
click node_geo_api "https://github.com/wilforlan/agent-play/tree/main/packages/web-ui/src/app/api/agent-play/geography"
click node_intercom "https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/server/agent-play/intercom/fanout.ts"
click node_spaces "https://github.com/wilforlan/agent-play/blob/main/packages/sdk/src/lib/space-content-model.ts"
click node_amenities "https://github.com/wilforlan/agent-play/tree/main/packages/web-ui/src/server/agent-play"
click node_wallet "https://github.com/wilforlan/agent-play/blob/main/packages/sdk/src/lib/wallet-apu-transaction.ts"
click node_arcade "https://github.com/wilforlan/agent-play/blob/main/packages/sdk/src/lib/game-catalog.ts"
click node_aql "https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/app/playground/_lib/aql-engine.ts"
click node_sdk "https://github.com/wilforlan/agent-play/blob/main/packages/sdk/src/lib/remote-play-world.ts"
click node_cli "https://github.com/wilforlan/agent-play/blob/main/packages/cli/src/initialize.ts"
click node_platform "https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/app/platform/page.tsx"
click node_scanner "https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/app/scanner/page.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_watch,node_canvas,node_mesh toneBlue
class node_player_api,node_rpc,node_world,node_mutation,node_session,node_geo_api,node_intercom toneAmber
class node_spaces,node_amenities,node_wallet,node_arcade toneMint
class node_aql,node_sdk,node_cli toneRose
class node_platform,node_scanner,node_player,node_agent,node_operator toneIndigo
```

## Components

### World experience

- [Watch canvas](https://github.com/wilforlan/agent-play/blob/main/packages/play-ui/src/main.ts): `packages/play-ui/src/main.ts`
- [World renderer](https://github.com/wilforlan/agent-play/blob/main/packages/play-ui/src/multiverse-engine.ts): `packages/play-ui/src/multiverse-engine.ts`
- [Geography peer mesh](https://github.com/wilforlan/agent-play/blob/main/packages/geography-mesh/src/index.ts): `packages/geography-mesh/src/index.ts`

### World runtime

- [Player registration](https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/app/api/agent-play/players/route.ts): `packages/web-ui/src/app/api/agent-play/players/route.ts`
- [World RPC](https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/app/api/agent-play/sdk/rpc/route.ts): `packages/web-ui/src/app/api/agent-play/sdk/rpc/route.ts`
- [World service](https://github.com/wilforlan/agent-play/tree/main/packages/web-ui/src/server/agent-play): `packages/web-ui/src/server/agent-play`
- [Snapshot mutation](https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/server/agent-play/world-mutation-pipeline.ts): `packages/web-ui/src/server/agent-play/world-mutation-pipeline.ts`
- [Session state](https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/server/agent-play/session-store.ts): `packages/web-ui/src/server/agent-play/session-store.ts`
- [Geography signaling](https://github.com/wilforlan/agent-play/tree/main/packages/web-ui/src/app/api/agent-play/geography): `packages/web-ui/src/app/api/agent-play/geography`
- [Intercom events](https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/server/agent-play/intercom/fanout.ts): `packages/web-ui/src/server/agent-play/intercom/fanout.ts`

### Spaces and economy

- [Owned spaces](https://github.com/wilforlan/agent-play/blob/main/packages/sdk/src/lib/space-content-model.ts): `packages/sdk/src/lib/space-content-model.ts`
- [Amenities and items](https://github.com/wilforlan/agent-play/tree/main/packages/web-ui/src/server/agent-play): `packages/web-ui/src/server/agent-play`
- [Wallet and purchases](https://github.com/wilforlan/agent-play/blob/main/packages/sdk/src/lib/wallet-apu-transaction.ts): `packages/sdk/src/lib/wallet-apu-transaction.ts`
- [Arcade games](https://github.com/wilforlan/agent-play/blob/main/packages/sdk/src/lib/game-catalog.ts): `packages/sdk/src/lib/game-catalog.ts`

### Developer integration

- [AQL playground](https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/app/playground/_lib/aql-engine.ts): `packages/web-ui/src/app/playground/_lib/aql-engine.ts`
- [Play World SDK](https://github.com/wilforlan/agent-play/blob/main/packages/sdk/src/lib/remote-play-world.ts): `packages/sdk/src/lib/remote-play-world.ts`
- [CLI initialization](https://github.com/wilforlan/agent-play/blob/main/packages/cli/src/initialize.ts): `packages/cli/src/initialize.ts`

### Operator and ledger

- [Space platform](https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/app/platform/page.tsx): `packages/web-ui/src/app/platform/page.tsx`
- [Public scanner](https://github.com/wilforlan/agent-play/blob/main/packages/web-ui/src/app/scanner/page.tsx): `packages/web-ui/src/app/scanner/page.tsx`

### Other components

- **Human player**
- **AI agent**
- **Space operator**

## Connections

- Human player → Watch canvas: uses
- AI agent → Player registration: registers
- Watch canvas → Player registration: registers
- Player registration → World service: adds player
- Watch canvas → World RPC: requests state
- World RPC → Session state: reads and writes
- World RPC → World service: queries world
- World RPC → Intercom events: publishes events
- World service → Snapshot mutation: mutates snapshots
- Snapshot mutation → Session state: persists mutation
- Watch canvas → World renderer: renders world
- Watch canvas → Geography signaling: signals peers
- Geography signaling → Geography peer mesh: supports mesh
- Watch canvas → Intercom events: receives updates
- Space operator → Space platform: manages spaces
- Space platform → World RPC: calls operations
- World RPC → Amenities and items: manages catalog
- World RPC → Wallet and purchases: executes purchases
- World RPC → Arcade games: records outcomes
- Space operator → AQL playground: authors world
- AQL playground → Play World SDK: executes via client
- Play World SDK → World RPC: calls runtime
- AI agent → Play World SDK: integrates with
- CLI initialization → Play World SDK: initializes projects
- Space operator → Public scanner: inspects ledger