# jvarzali/sokoban-environment architecture

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

- Interactive diagram: https://gitdiagram.com/jvarzali/sokoban-environment
- Repository: https://github.com/jvarzali/sokoban-environment

## Overview

Sokoban is a two-height-grid puzzle environment exposed as a step-based agent API, with a browser replay viewer for inspecting exported runs. The main workflow is: an agent resets an episode, receives a map observation, submits directional actions, and receives updated observations and an efficiency-based win reward. The environment loads authored maps and applies movement, ramp, and box rules. The viewer separately replays exported runs through a JavaScript engine and renders them in 2D or 3D. The graph follows documented wiring; some viewer module details are based on the README rather than sampled source.

Main entry points: [`src/env_sdk.py`](https://github.com/jvarzali/sokoban-environment/blob/main/src/env_sdk.py) (Episode HTTP Server), [`env.py`](https://github.com/jvarzali/sokoban-environment/blob/main/env.py) (Game Engine), [`docs/app.js`](https://github.com/jvarzali/sokoban-environment/blob/main/docs/app.js) (View Controller), [`docs/replay.js`](https://github.com/jvarzali/sokoban-environment/blob/main/docs/replay.js) (Replay Playback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_environment["Game Environment"]
  node_engine["Game Engine<br/>[env.py]"]
  node_rules["Movement Rules<br/>[env.py]"]
  node_observations["Observations &amp; Reward<br/>[env.py]"]
end

subgraph group_interface["Agent Interface"]
  node_adapter["HTTP Adapter<br/>[adapter.py]"]
  node_sdk["Episode HTTP Server<br/>[env_sdk.py]"]
end

subgraph group_content["Puzzle Content"]
  node_maps[("Authored Maps")]
  node_benchmark["Benchmark Config<br/>[benchanything.json]"]
  node_prompt["Agent Rules Prompt<br/>[system_prompt.txt]"]
end

subgraph group_viewer["Replay Viewer"]
  node_exports["Run Exports"]
  node_replay["Replay Playback<br/>[replay.js]"]
  node_jsengine["Replay Engine<br/>[game.js]"]
  node_controller["View Controller<br/>[app.js]"]
  node_renderer2d["2D Renderer<br/>[view2d.js]"]
  node_renderer3d["3D Renderer<br/>[view3d.js]"]
  node_bundledmaps["Bundled Maps<br/>[maps.js]"]
end

node_agent(("Agent"))
node_platform(("Mesocosm Platform"))

node_platform -.->|"provides prompt"| node_agent
node_platform -->|"sends episode requests"| node_adapter
node_adapter -->|"starts server"| node_sdk
node_sdk -->|"routes reset/step"| node_engine
node_agent -->|"submits actions"| node_sdk
node_sdk -->|"returns results"| node_agent
node_engine -->|"loads maps"| node_maps
node_engine -->|"applies moves"| node_rules
node_engine -->|"builds results"| node_observations
node_observations -->|"returns observation/reward"| node_sdk
node_benchmark -->|"configures runs"| node_platform
node_prompt -->|"supplies game rules"| node_platform
node_agent -->|"produces run data"| node_exports
node_exports -->|"loads run"| node_replay
node_replay -->|"re-simulates moves"| node_jsengine
node_replay -->|"drives playback"| node_controller
node_controller -->|"controls view"| node_renderer2d
node_controller -->|"controls view"| node_renderer3d
node_bundledmaps -.->|"provides maps"| node_controller

click node_engine "https://github.com/jvarzali/sokoban-environment/blob/main/env.py"
click node_rules "https://github.com/jvarzali/sokoban-environment/blob/main/env.py"
click node_observations "https://github.com/jvarzali/sokoban-environment/blob/main/env.py"
click node_maps "https://github.com/jvarzali/sokoban-environment/tree/main/maps"
click node_benchmark "https://github.com/jvarzali/sokoban-environment/blob/main/benchanything.json"
click node_prompt "https://github.com/jvarzali/sokoban-environment/blob/main/system_prompt.txt"
click node_adapter "https://github.com/jvarzali/sokoban-environment/blob/main/adapter.py"
click node_sdk "https://github.com/jvarzali/sokoban-environment/blob/main/src/env_sdk.py"
click node_exports "https://github.com/jvarzali/sokoban-environment/tree/main/docs/runs"
click node_replay "https://github.com/jvarzali/sokoban-environment/blob/main/docs/replay.js"
click node_jsengine "https://github.com/jvarzali/sokoban-environment/blob/main/docs/game.js"
click node_controller "https://github.com/jvarzali/sokoban-environment/blob/main/docs/app.js"
click node_renderer2d "https://github.com/jvarzali/sokoban-environment/blob/main/docs/view2d.js"
click node_renderer3d "https://github.com/jvarzali/sokoban-environment/blob/main/docs/view3d.js"
click node_bundledmaps "https://github.com/jvarzali/sokoban-environment/blob/main/docs/maps.js"

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_engine,node_rules,node_observations toneBlue
class node_adapter,node_sdk toneAmber
class node_maps,node_benchmark,node_prompt toneMint
class node_exports,node_replay,node_jsengine,node_controller,node_renderer2d,node_renderer3d,node_bundledmaps toneRose
class node_agent,node_platform toneIndigo
```

## Components

### Game Environment

- [Game Engine](https://github.com/jvarzali/sokoban-environment/blob/main/env.py): `env.py`
- [Movement Rules](https://github.com/jvarzali/sokoban-environment/blob/main/env.py): `env.py`
- [Observations & Reward](https://github.com/jvarzali/sokoban-environment/blob/main/env.py): `env.py`

### Agent Interface

- [HTTP Adapter](https://github.com/jvarzali/sokoban-environment/blob/main/adapter.py): `adapter.py`
- [Episode HTTP Server](https://github.com/jvarzali/sokoban-environment/blob/main/src/env_sdk.py): `src/env_sdk.py`

### Puzzle Content

- [Authored Maps](https://github.com/jvarzali/sokoban-environment/tree/main/maps): `maps`
- [Benchmark Config](https://github.com/jvarzali/sokoban-environment/blob/main/benchanything.json): `benchanything.json`
- [Agent Rules Prompt](https://github.com/jvarzali/sokoban-environment/blob/main/system_prompt.txt): `system_prompt.txt`

### Replay Viewer

- [Run Exports](https://github.com/jvarzali/sokoban-environment/tree/main/docs/runs): `docs/runs`
- [Replay Playback](https://github.com/jvarzali/sokoban-environment/blob/main/docs/replay.js): `docs/replay.js`
- [Replay Engine](https://github.com/jvarzali/sokoban-environment/blob/main/docs/game.js): `docs/game.js`
- [View Controller](https://github.com/jvarzali/sokoban-environment/blob/main/docs/app.js): `docs/app.js`
- [2D Renderer](https://github.com/jvarzali/sokoban-environment/blob/main/docs/view2d.js): `docs/view2d.js`
- [3D Renderer](https://github.com/jvarzali/sokoban-environment/blob/main/docs/view3d.js): `docs/view3d.js`
- [Bundled Maps](https://github.com/jvarzali/sokoban-environment/blob/main/docs/maps.js): `docs/maps.js`

### Other components

- **Agent**
- **Mesocosm Platform**

## Connections

- Mesocosm Platform → Agent: provides prompt
- Mesocosm Platform → HTTP Adapter: sends episode requests
- HTTP Adapter → Episode HTTP Server: starts server
- Episode HTTP Server → Game Engine: routes reset/step
- Agent → Episode HTTP Server: submits actions
- Episode HTTP Server → Agent: returns results
- Game Engine → Authored Maps: loads maps
- Game Engine → Movement Rules: applies moves
- Game Engine → Observations & Reward: builds results
- Observations & Reward → Episode HTTP Server: returns observation/reward
- Benchmark Config → Mesocosm Platform: configures runs
- Agent Rules Prompt → Mesocosm Platform: supplies game rules
- Agent → Run Exports: produces run data
- Run Exports → Replay Playback: loads run
- Replay Playback → Replay Engine: re-simulates moves
- Replay Playback → View Controller: drives playback
- View Controller → 2D Renderer: controls view
- View Controller → 3D Renderer: controls view
- Bundled Maps → View Controller: provides maps