# mikamika06/ploshcha architecture

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

- Interactive diagram: https://gitdiagram.com/mikamika06/ploshcha
- Repository: https://github.com/mikamika06/ploshcha

## Overview

Площа is an interactive Ukrainian village that presents agent-core telemetry as a living scene. A visitor posts a topic on the bulletin board; the live service queues it, the simulation runs a village discussion, and events stream back for the browser to validate, reduce into state, and render as movement and dialogue. The repository also contains a research/evaluation mode separate from the production viche. Connections among unsampled server and storage internals are limited to documented README behavior; paths identify their existing source areas.

Main entry points: [`services/sim/ploshcha_sim/live/server.py`](https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/live/server.py) (Live API), [`apps/web/src/store/SimStore.ts`](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/store/SimStore.ts) (Event state), [`apps/web/src/net/LiveDriver.ts`](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/net/LiveDriver.ts) (Live driver), [`apps/web/src/main.ts`](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/main.ts) (Village app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Village frontend"]
  node_webapp["Village app<br/>[main.ts]"]
  node_board["Bulletin board<br/>[Board.ts]"]
  node_talk["Group dialogue<br/>[GroupTalk.ts]"]
  node_living["Living room<br/>[LivingRoom.ts]"]
  node_inspector["Villager inspector<br/>[Inspector.ts]"]
  node_director["Agent movement<br/>[AgentDirector.ts]"]
  node_walkgrid["Walk grid<br/>[WalkGrid.ts]"]
  node_renderer["Village scene<br/>[SceneRenderer.ts]"]
  node_store[("Event state<br/>[SimStore.ts]")]
  node_liveclient["Live driver<br/>[LiveDriver.ts]"]
  node_fixture["Fixture driver<br/>[FixtureDriver.ts]"]
  node_session["Guest session<br/>[session.ts]"]
end

subgraph group_runtime["Live runtime"]
  node_api["Live API<br/>[server.py]"]
  node_queue[("Work queue<br/>[queue_sqlite.py]")]
  node_runner["Live runner<br/>[runner.py]"]
  node_composer["Runtime composition<br/>[compose.py]"]
end

subgraph group_agents["Simulation agents"]
  node_viche["Village simulation<br/>[viche.py]"]
  node_orchestrator["Task orchestration<br/>[orchestrator.py]"]
end

subgraph group_infra["Ports and state"]
  node_router["Model routing<br/>[router_profile.py]"]
  node_llm["Language model port<br/>[llm.py]"]
  node_memory[("Village memory<br/>[memory_sqlite.py]")]
end

subgraph group_research["Contracts and research"]
  node_contracts["Event contract<br/>[events.ts]"]
  node_validator["Event validation<br/>[validate.ts]"]
  node_evalkit["Research evaluation<br/>[conditions.py]"]
end

node_visitor(("Visitor"))
node_modelservice(("Mamay and Lapa"))

node_visitor -->|"posts topic"| node_board
node_board -.->|"submits command"| node_liveclient
node_webapp -->|"sends commands"| node_liveclient
node_webapp -->|"mounts scene"| node_renderer
node_webapp -.->|"updates from events"| node_store
node_liveclient -.->|"requests events"| node_api
node_session -.->|"identifies guest"| node_api
node_api -.->|"queues topic"| node_queue
node_api -.->|"serves live runtime"| node_runner
node_runner -.->|"runs discussion"| node_viche
node_runner -.->|"processes queued work"| node_queue
node_composer -->|"builds simulation"| node_viche
node_composer -->|"configures routing"| node_router
node_viche -.->|"requests model output"| node_modelservice
node_orchestrator -.->|"routes model steps"| node_router
node_router -->|"selects model port"| node_llm
node_api -.->|"persists village state"| node_memory
node_liveclient -->|"validates events"| node_validator
node_fixture -->|"validates fixture events"| node_validator
node_validator -->|"checks event shapes"| node_contracts
node_store -->|"reduces typed events"| node_contracts
node_store -->|"provides villager state"| node_inspector
node_store -.->|"provides dialogue state"| node_talk
node_director -->|"plans movement"| node_walkgrid
node_renderer -.->|"uses path grid"| node_walkgrid
node_evalkit -->|"defines research conditions"| node_composer

click node_webapp "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/main.ts"
click node_board "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/interact/Board.ts"
click node_talk "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/interact/GroupTalk.ts"
click node_living "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/interact/LivingRoom.ts"
click node_inspector "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/interact/Inspector.ts"
click node_director "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/agents/AgentDirector.ts"
click node_walkgrid "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/agents/WalkGrid.ts"
click node_renderer "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/scene/SceneRenderer.ts"
click node_store "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/store/SimStore.ts"
click node_liveclient "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/net/LiveDriver.ts"
click node_fixture "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/net/FixtureDriver.ts"
click node_session "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/net/session.ts"
click node_api "https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/live/server.py"
click node_queue "https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/adapters/queue_sqlite.py"
click node_runner "https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/live/runner.py"
click node_composer "https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/compose.py"
click node_viche "https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/agents/viche.py"
click node_orchestrator "https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/agents/orchestrator.py"
click node_router "https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/adapters/router_profile.py"
click node_llm "https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/ports/llm.py"
click node_memory "https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/adapters/memory_sqlite.py"
click node_contracts "https://github.com/mikamika06/ploshcha/blob/main/packages/contract-ts/src/events.ts"
click node_validator "https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/net/validate.ts"
click node_evalkit "https://github.com/mikamika06/ploshcha/blob/main/services/sim/evalkit/conditions.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_webapp,node_board,node_talk,node_living,node_inspector,node_director,node_walkgrid,node_renderer,node_store,node_liveclient,node_fixture,node_session toneBlue
class node_api,node_queue,node_runner,node_composer toneAmber
class node_viche,node_orchestrator toneMint
class node_router,node_llm,node_memory toneRose
class node_contracts,node_validator,node_evalkit,node_visitor,node_modelservice toneIndigo
```

## Components

### Village frontend

- [Village app](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/main.ts): `apps/web/src/main.ts`
- [Bulletin board](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/interact/Board.ts): `apps/web/src/interact/Board.ts`
- [Group dialogue](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/interact/GroupTalk.ts): `apps/web/src/interact/GroupTalk.ts`
- [Living room](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/interact/LivingRoom.ts): `apps/web/src/interact/LivingRoom.ts`
- [Villager inspector](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/interact/Inspector.ts): `apps/web/src/interact/Inspector.ts`
- [Agent movement](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/agents/AgentDirector.ts): `apps/web/src/agents/AgentDirector.ts`
- [Walk grid](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/agents/WalkGrid.ts): `apps/web/src/agents/WalkGrid.ts`
- [Village scene](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/scene/SceneRenderer.ts): `apps/web/src/scene/SceneRenderer.ts`
- [Event state](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/store/SimStore.ts): `apps/web/src/store/SimStore.ts`
- [Live driver](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/net/LiveDriver.ts): `apps/web/src/net/LiveDriver.ts`
- [Fixture driver](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/net/FixtureDriver.ts): `apps/web/src/net/FixtureDriver.ts`
- [Guest session](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/net/session.ts): `apps/web/src/net/session.ts`

### Live runtime

- [Live API](https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/live/server.py): `services/sim/ploshcha_sim/live/server.py`
- [Work queue](https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/adapters/queue_sqlite.py): `services/sim/ploshcha_sim/adapters/queue_sqlite.py`
- [Live runner](https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/live/runner.py): `services/sim/ploshcha_sim/live/runner.py`
- [Runtime composition](https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/compose.py): `services/sim/ploshcha_sim/compose.py`

### Simulation agents

- [Village simulation](https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/agents/viche.py): `services/sim/ploshcha_sim/agents/viche.py`
- [Task orchestration](https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/agents/orchestrator.py): `services/sim/ploshcha_sim/agents/orchestrator.py`

### Ports and state

- [Model routing](https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/adapters/router_profile.py): `services/sim/ploshcha_sim/adapters/router_profile.py`
- [Language model port](https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/ports/llm.py): `services/sim/ploshcha_sim/ports/llm.py`
- [Village memory](https://github.com/mikamika06/ploshcha/blob/main/services/sim/ploshcha_sim/adapters/memory_sqlite.py): `services/sim/ploshcha_sim/adapters/memory_sqlite.py`

### Contracts and research

- [Event contract](https://github.com/mikamika06/ploshcha/blob/main/packages/contract-ts/src/events.ts): `packages/contract-ts/src/events.ts`
- [Event validation](https://github.com/mikamika06/ploshcha/blob/main/apps/web/src/net/validate.ts): `apps/web/src/net/validate.ts`
- [Research evaluation](https://github.com/mikamika06/ploshcha/blob/main/services/sim/evalkit/conditions.py): `services/sim/evalkit/conditions.py`

### Other components

- **Visitor**
- **Mamay and Lapa**

## Connections

- Visitor → Bulletin board: posts topic
- Bulletin board → Live driver: submits command
- Village app → Live driver: sends commands (evidence: `apps/web/src/main.ts`)
- Village app → Village scene: mounts scene (evidence: `apps/web/src/main.ts`)
- Village app → Event state: updates from events (evidence: `apps/web/src/main.ts`)
- Live driver → Live API: requests events
- Guest session → Live API: identifies guest (evidence: `apps/web/src/net/session.ts`)
- Live API → Work queue: queues topic
- Live API → Live runner: serves live runtime
- Live runner → Village simulation: runs discussion
- Live runner → Work queue: processes queued work
- Runtime composition → Village simulation: builds simulation (evidence: `services/sim/ploshcha_sim/compose.py`)
- Runtime composition → Model routing: configures routing (evidence: `services/sim/ploshcha_sim/compose.py`)
- Village simulation → Mamay and Lapa: requests model output
- Task orchestration → Model routing: routes model steps (evidence: `services/sim/ploshcha_sim/agents/orchestrator.py`)
- Model routing → Language model port: selects model port (evidence: `services/sim/ploshcha_sim/adapters/router_profile.py`)
- Live API → Village memory: persists village state
- Live driver → Event validation: validates events (evidence: `apps/web/src/net/LiveDriver.ts`)
- Fixture driver → Event validation: validates fixture events (evidence: `apps/web/src/net/FixtureDriver.ts`)
- Event validation → Event contract: checks event shapes (evidence: `apps/web/src/net/validate.ts`)
- Event state → Event contract: reduces typed events (evidence: `apps/web/src/store/SimStore.ts`)
- Event state → Villager inspector: provides villager state (evidence: `apps/web/src/interact/Inspector.ts`)
- Event state → Group dialogue: provides dialogue state (evidence: `apps/web/src/main.ts`)
- Agent movement → Walk grid: plans movement (evidence: `apps/web/src/agents/AgentDirector.ts`)
- Village scene → Walk grid: uses path grid (evidence: `apps/web/src/main.ts`)
- Research evaluation → Runtime composition: defines research conditions (evidence: `services/sim/evalkit/conditions.py`)
