# artunbalta/echo architecture

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

- Interactive diagram: https://gitdiagram.com/artunbalta/echo
- Repository: https://github.com/artunbalta/echo

## Overview

ECHO is a browser-based virtual world whose central experience is walking through a village, encountering small behavioral moments, and opening predictions sealed by a personal “echo.” The world, procedural planet, and envelope-based predictions are the principal user-facing stages; a separate optional ML service learns an eight-axis persona from behavioral signals. The README also describes friend-prediction links, an opt-in pilot, and public twin-audit research. Some subsystem links are documented only at product level; unsampled route wiring is not inferred.

Main entry points: [`packages/planet/lib/scene.ts`](https://github.com/artunbalta/echo/blob/main/packages/planet/lib/scene.ts) (Planet scene), [`services/ml/echo_ml/persona.py`](https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/persona.py) (Persona model), [`apps/web/src/game/WorldCore.ts`](https://github.com/artunbalta/echo/blob/main/apps/web/src/game/WorldCore.ts) (World engine), [`apps/web/src/components/WorldClient.tsx`](https://github.com/artunbalta/echo/blob/main/apps/web/src/components/WorldClient.tsx) (World client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["World experience"]
  node_world_client["World client<br/>[WorldClient.tsx]"]
  node_world_core["World engine<br/>[WorldCore.ts]"]
  node_world_routes["World actions API<br/>[route.ts]"]
  node_envelopes["Sealed envelopes<br/>[envelopes.ts]"]
end

subgraph group_world["World simulation"]
  node_planet_scene["Planet scene<br/>[scene.ts]"]
  node_planet_terrain["Terrain<br/>[terrain.ts]"]
  node_planet_assets["World affordances<br/>[assets.ts]"]
  node_planet_moments["Behavioral moments<br/>[moments.ts]"]
  node_planet_society["Village society<br/>[society.ts]"]
end

subgraph group_echo["Echo and prediction"]
  node_behavior_api["Behavioral API<br/>[route.ts]"]
  node_ml_app["Learning service<br/>[app.py]"]
  node_event_ingest["Event ingestion<br/>[ingest.py]"]
  node_persona["Persona model<br/>[persona.py]"]
  node_persona_axes["Eight axes<br/>[persona_axes.py]"]
  node_embeddings["Signal embeddings<br/>[embeddings.py]"]
  node_persona_model["Persona inference<br/>[persona_model.py]"]
end

subgraph group_services["Supporting services"]
  node_venue_dialogue["Venue dialogue<br/>[live-engine.ts]"]
  node_venue_outcome["Dialogue outcomes<br/>[outcome.ts]"]
end

subgraph group_research["Research"]
  node_pilot["Friend prediction pilot<br/>[engine.py]"]
  node_twin_audit["Twin audit research<br/>[fair_llm_twin2k.py]"]
end

node_visitor(("Player"))

node_visitor -->|"enters"| node_world_client
node_world_client -.->|"renders"| node_world_core
node_world_core -.->|"submits actions"| node_world_routes
node_visitor -->|"opens predictions"| node_envelopes
node_world_core -.->|"renders world"| node_planet_scene
node_planet_scene -.->|"uses terrain"| node_planet_terrain
node_planet_scene -.->|"uses affordances"| node_planet_assets
node_planet_scene -.->|"hosts moments"| node_planet_moments
node_planet_scene -.->|"populates villages"| node_planet_society
node_behavior_api -.->|"forwards signals"| node_ml_app
node_ml_app -->|"routes events"| node_event_ingest
node_event_ingest -->|"derives observations"| node_persona
node_persona -->|"uses axis definitions"| node_persona_axes
node_persona -->|"uses embeddings"| node_embeddings
node_persona -->|"uses inference model"| node_persona_model
node_venue_dialogue -->|"resolves outcomes"| node_venue_outcome
node_visitor -->|"predicts friends"| node_pilot
node_visitor -->|"audits twins"| node_twin_audit

click node_world_client "https://github.com/artunbalta/echo/blob/main/apps/web/src/components/WorldClient.tsx"
click node_world_core "https://github.com/artunbalta/echo/blob/main/apps/web/src/game/WorldCore.ts"
click node_world_routes "https://github.com/artunbalta/echo/blob/main/apps/web/src/app/api/world/act/route.ts"
click node_envelopes "https://github.com/artunbalta/echo/blob/main/apps/web/src/lib/knowable/envelopes.ts"
click node_planet_scene "https://github.com/artunbalta/echo/blob/main/packages/planet/lib/scene.ts"
click node_planet_terrain "https://github.com/artunbalta/echo/blob/main/packages/planet/lib/terrain.ts"
click node_planet_assets "https://github.com/artunbalta/echo/blob/main/packages/planet/lib/assets.ts"
click node_planet_moments "https://github.com/artunbalta/echo/blob/main/packages/planet/lib/moments.ts"
click node_planet_society "https://github.com/artunbalta/echo/blob/main/packages/planet/lib/society.ts"
click node_behavior_api "https://github.com/artunbalta/echo/blob/main/apps/web/src/app/api/observe/behavioral/route.ts"
click node_ml_app "https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/app.py"
click node_event_ingest "https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/ingest.py"
click node_persona "https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/persona.py"
click node_persona_axes "https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/persona_axes.py"
click node_embeddings "https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/embeddings.py"
click node_persona_model "https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/persona_model.py"
click node_venue_dialogue "https://github.com/artunbalta/echo/blob/main/apps/web/src/lib/venue/dialogue/live-engine.ts"
click node_venue_outcome "https://github.com/artunbalta/echo/blob/main/apps/web/src/lib/venue/npc/outcome.ts"
click node_pilot "https://github.com/artunbalta/echo/blob/main/research/pilot/echo_pilot/engine.py"
click node_twin_audit "https://github.com/artunbalta/echo/blob/main/research/deeds/fair_llm_twin2k.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_world_client,node_world_core,node_world_routes,node_envelopes toneBlue
class node_planet_scene,node_planet_terrain,node_planet_assets,node_planet_moments,node_planet_society toneAmber
class node_behavior_api,node_ml_app,node_event_ingest,node_persona,node_persona_axes,node_embeddings,node_persona_model toneMint
class node_venue_dialogue,node_venue_outcome toneRose
class node_pilot,node_twin_audit,node_visitor toneIndigo
```

## Components

### World experience

- [World client](https://github.com/artunbalta/echo/blob/main/apps/web/src/components/WorldClient.tsx): `apps/web/src/components/WorldClient.tsx`
- [World engine](https://github.com/artunbalta/echo/blob/main/apps/web/src/game/WorldCore.ts): `apps/web/src/game/WorldCore.ts`
- [World actions API](https://github.com/artunbalta/echo/blob/main/apps/web/src/app/api/world/act/route.ts): `apps/web/src/app/api/world/act/route.ts`
- [Sealed envelopes](https://github.com/artunbalta/echo/blob/main/apps/web/src/lib/knowable/envelopes.ts): `apps/web/src/lib/knowable/envelopes.ts`

### World simulation

- [Planet scene](https://github.com/artunbalta/echo/blob/main/packages/planet/lib/scene.ts): `packages/planet/lib/scene.ts`
- [Terrain](https://github.com/artunbalta/echo/blob/main/packages/planet/lib/terrain.ts): `packages/planet/lib/terrain.ts`
- [World affordances](https://github.com/artunbalta/echo/blob/main/packages/planet/lib/assets.ts): `packages/planet/lib/assets.ts`
- [Behavioral moments](https://github.com/artunbalta/echo/blob/main/packages/planet/lib/moments.ts): `packages/planet/lib/moments.ts`
- [Village society](https://github.com/artunbalta/echo/blob/main/packages/planet/lib/society.ts): `packages/planet/lib/society.ts`

### Echo and prediction

- [Behavioral API](https://github.com/artunbalta/echo/blob/main/apps/web/src/app/api/observe/behavioral/route.ts): `apps/web/src/app/api/observe/behavioral/route.ts`
- [Learning service](https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/app.py): `services/ml/echo_ml/app.py`
- [Event ingestion](https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/ingest.py): `services/ml/echo_ml/ingest.py`
- [Persona model](https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/persona.py): `services/ml/echo_ml/persona.py`
- [Eight axes](https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/persona_axes.py): `services/ml/echo_ml/persona_axes.py`
- [Signal embeddings](https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/embeddings.py): `services/ml/echo_ml/embeddings.py`
- [Persona inference](https://github.com/artunbalta/echo/blob/main/services/ml/echo_ml/persona_model.py): `services/ml/echo_ml/persona_model.py`

### Supporting services

- [Venue dialogue](https://github.com/artunbalta/echo/blob/main/apps/web/src/lib/venue/dialogue/live-engine.ts): `apps/web/src/lib/venue/dialogue/live-engine.ts`
- [Dialogue outcomes](https://github.com/artunbalta/echo/blob/main/apps/web/src/lib/venue/npc/outcome.ts): `apps/web/src/lib/venue/npc/outcome.ts`

### Research

- [Friend prediction pilot](https://github.com/artunbalta/echo/blob/main/research/pilot/echo_pilot/engine.py): `research/pilot/echo_pilot/engine.py`
- [Twin audit research](https://github.com/artunbalta/echo/blob/main/research/deeds/fair_llm_twin2k.py): `research/deeds/fair_llm_twin2k.py`

### Other components

- **Player**

## Connections

- Player → World client: enters (evidence: `README.md`)
- World client → World engine: renders
- World engine → World actions API: submits actions
- Player → Sealed envelopes: opens predictions (evidence: `README.md`)
- World engine → Planet scene: renders world
- Planet scene → Terrain: uses terrain
- Planet scene → World affordances: uses affordances (evidence: `packages/planet/lib/assets.ts`)
- Planet scene → Behavioral moments: hosts moments
- Planet scene → Village society: populates villages
- Behavioral API → Learning service: forwards signals
- Learning service → Event ingestion: routes events (evidence: `services/ml/echo_ml/app.py`)
- Event ingestion → Persona model: derives observations (evidence: `services/ml/echo_ml/ingest.py`)
- Persona model → Eight axes: uses axis definitions (evidence: `services/ml/echo_ml/persona.py`)
- Persona model → Signal embeddings: uses embeddings (evidence: `services/ml/echo_ml/persona.py`)
- Persona model → Persona inference: uses inference model (evidence: `services/ml/echo_ml/persona.py`)
- Venue dialogue → Dialogue outcomes: resolves outcomes (evidence: `apps/web/src/lib/venue/dialogue/live-engine.ts`)
- Player → Friend prediction pilot: predicts friends (evidence: `README.md`)
- Player → Twin audit research: audits twins (evidence: `README.md`)
