# simhacker/micropolis architecture

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

- Interactive diagram: https://gitdiagram.com/simhacker/micropolis
- Repository: https://github.com/simhacker/micropolis

## Overview

Micropolis is a city-building simulation distributed here as several historical implementations and interfaces. The principal workflow is a player opening a client, issuing city-building or simulation commands, and viewing the resulting city state. The newer MicropolisCore separates simulation, Python-facing engines, and tile rendering; the repository also contains a Java desktop client, Python/GTK and TurboGears frontends, and the legacy Tcl/Tk activity. Several legacy links are documented only at a high level, so those relationships are dashed and uncited.

Main entry points: [`MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisgenericengine.py`](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisgenericengine.py) (Python Engine), [`MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisturbogearsengine.py`](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisturbogearsengine.py) (Web Game Engine), [`turbogears/micropolis/controllers.py`](https://github.com/simhacker/micropolis/blob/master/turbogears/micropolis/controllers.py) (Web Controller), [`MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisrobot.py`](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisrobot.py) (City Robots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["City Simulation"]
  node_city_engine["City Engine<br/>[micropolis.cpp]"]
  node_city_rules["Simulation Rules<br/>[simulate.cpp]"]
  node_city_map["Map State<br/>[map.cpp]"]
  node_tile_renderer["Tile Renderer<br/>[tileengine.cpp]"]
end

subgraph group_python["Python Clients"]
  node_python_engine["Python Engine"]
  node_py_zone["City Zones<br/>[micropoliszone.py]"]
  node_py_robot["City Robots<br/>[micropolisrobot.py]"]
  node_py_tool["City Tools<br/>[micropolistool.py]"]
  node_py_gtk["GTK Frontend<br/>[main.py]"]
  node_py_views["GTK Views"]
  node_cell_engine["Cell Automata<br/>[cellengine.cpp]"]
  node_cell_ui["Cell Interface<br/>[cellengine.py]"]
end

subgraph group_web["Web Game"]
  node_web_client["Web Client<br/>[micropolis.js]"]
  node_web_controller["Web Controller<br/>[controllers.py]"]
  node_web_engine["Web Game Engine"]
  node_city_model[("City Persistence<br/>[model.py]")]
end

subgraph group_java["Java Client"]
  node_java_entry["Desktop Entry<br/>[Main.java]"]
  node_java_ui["Desktop Window<br/>[MainWindow.java]"]
  node_java_engine["Java Simulation<br/>[Micropolis.java]"]
end

subgraph group_legacy["Legacy Activity"]
  node_tcl_ui["Tcl/Tk Interface<br/>[main.c]"]
  node_legacy_sim["Legacy Simulator<br/>[sim.c]"]
  node_activity["Activity Shell"]
end

node_player(("Player"))

node_player -.->|"opens"| node_py_gtk
node_py_gtk -.->|"starts"| node_py_views
node_py_views -.->|"uses"| node_python_engine
node_python_engine -->|"creates zones"| node_py_zone
node_python_engine -.->|"renders tiles"| node_tile_renderer
node_python_engine -.->|"extends engine"| node_city_engine
node_python_engine -->|"simulates robots"| node_py_robot
node_py_zone -->|"uses tools"| node_py_robot
node_player -.->|"interacts"| node_cell_ui
node_cell_ui -.->|"controls"| node_cell_engine
node_player -.->|"plays"| node_web_client
node_web_client -.->|"sends commands"| node_web_controller
node_web_controller -->|"creates sessions"| node_web_engine
node_web_engine -->|"inherits"| node_python_engine
node_web_engine -->|"uses"| node_py_robot
node_web_controller -->|"queries"| node_city_model
node_web_engine -->|"uses persistence"| node_city_model
node_player -->|"launches"| node_java_entry
node_java_entry -->|"opens window"| node_java_ui
node_java_ui -->|"uses"| node_java_engine
node_player -.->|"starts activity"| node_activity
node_activity -.->|"launches"| node_tcl_ui
node_tcl_ui -.->|"drives simulation"| node_legacy_sim

click node_city_engine "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/MicropolisEngine/src/micropolis.cpp"
click node_city_rules "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/MicropolisEngine/src/simulate.cpp"
click node_city_map "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/MicropolisEngine/src/map.cpp"
click node_tile_renderer "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/TileEngine/src/tileengine.cpp"
click node_python_engine "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisgenericengine.py"
click node_py_zone "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropoliszone.py"
click node_py_robot "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisrobot.py"
click node_py_tool "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolistool.py"
click node_py_gtk "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/gtkFrontend/main.py"
click node_py_views "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisgtkengine.py"
click node_cell_engine "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/CellEngine/src/cellengine.cpp"
click node_cell_ui "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/cellEngine/cellengine.py"
click node_web_client "https://github.com/simhacker/micropolis/blob/master/turbogears/micropolis/htdocs/static/javascript/micropolis.js"
click node_web_controller "https://github.com/simhacker/micropolis/blob/master/turbogears/micropolis/controllers.py"
click node_web_engine "https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisturbogearsengine.py"
click node_city_model "https://github.com/simhacker/micropolis/blob/master/turbogears/micropolis/model.py"
click node_java_entry "https://github.com/simhacker/micropolis/blob/master/micropolis-java/src/micropolisj/Main.java"
click node_java_ui "https://github.com/simhacker/micropolis/blob/master/micropolis-java/src/micropolisj/gui/MainWindow.java"
click node_java_engine "https://github.com/simhacker/micropolis/blob/master/micropolis-java/src/micropolisj/engine/Micropolis.java"
click node_tcl_ui "https://github.com/simhacker/micropolis/blob/master/micropolis-activity/src/tclx/tkucbsrc/main.c"
click node_legacy_sim "https://github.com/simhacker/micropolis/blob/master/micropolis-activity/src/sim/sim.c"
click node_activity "https://github.com/simhacker/micropolis/blob/master/micropolis-activity/micropolisactivity.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_city_engine,node_city_rules,node_city_map,node_tile_renderer toneBlue
class node_python_engine,node_py_zone,node_py_robot,node_py_tool,node_py_gtk,node_py_views,node_cell_engine,node_cell_ui toneAmber
class node_web_client,node_web_controller,node_web_engine,node_city_model toneMint
class node_java_entry,node_java_ui,node_java_engine toneRose
class node_tcl_ui,node_legacy_sim,node_activity,node_player toneIndigo
```

## Components

### City Simulation

- [City Engine](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/MicropolisEngine/src/micropolis.cpp): `MicropolisCore/src/MicropolisEngine/src/micropolis.cpp`
- [Simulation Rules](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/MicropolisEngine/src/simulate.cpp): `MicropolisCore/src/MicropolisEngine/src/simulate.cpp`
- [Map State](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/MicropolisEngine/src/map.cpp): `MicropolisCore/src/MicropolisEngine/src/map.cpp`
- [Tile Renderer](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/TileEngine/src/tileengine.cpp): `MicropolisCore/src/TileEngine/src/tileengine.cpp`

### Python Clients

- [Python Engine](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisgenericengine.py): `MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisgenericengine.py`
- [City Zones](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropoliszone.py): `MicropolisCore/src/pyMicropolis/micropolisEngine/micropoliszone.py`
- [City Robots](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisrobot.py): `MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisrobot.py`
- [City Tools](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolistool.py): `MicropolisCore/src/pyMicropolis/micropolisEngine/micropolistool.py`
- [GTK Frontend](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/gtkFrontend/main.py): `MicropolisCore/src/pyMicropolis/gtkFrontend/main.py`
- [GTK Views](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisgtkengine.py): `MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisgtkengine.py`
- [Cell Automata](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/CellEngine/src/cellengine.cpp): `MicropolisCore/src/CellEngine/src/cellengine.cpp`
- [Cell Interface](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/cellEngine/cellengine.py): `MicropolisCore/src/pyMicropolis/cellEngine/cellengine.py`

### Web Game

- [Web Client](https://github.com/simhacker/micropolis/blob/master/turbogears/micropolis/htdocs/static/javascript/micropolis.js): `turbogears/micropolis/htdocs/static/javascript/micropolis.js`
- [Web Controller](https://github.com/simhacker/micropolis/blob/master/turbogears/micropolis/controllers.py): `turbogears/micropolis/controllers.py`
- [Web Game Engine](https://github.com/simhacker/micropolis/blob/master/MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisturbogearsengine.py): `MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisturbogearsengine.py`
- [City Persistence](https://github.com/simhacker/micropolis/blob/master/turbogears/micropolis/model.py): `turbogears/micropolis/model.py`

### Java Client

- [Desktop Entry](https://github.com/simhacker/micropolis/blob/master/micropolis-java/src/micropolisj/Main.java): `micropolis-java/src/micropolisj/Main.java`
- [Desktop Window](https://github.com/simhacker/micropolis/blob/master/micropolis-java/src/micropolisj/gui/MainWindow.java): `micropolis-java/src/micropolisj/gui/MainWindow.java`
- [Java Simulation](https://github.com/simhacker/micropolis/blob/master/micropolis-java/src/micropolisj/engine/Micropolis.java): `micropolis-java/src/micropolisj/engine/Micropolis.java`

### Legacy Activity

- [Tcl/Tk Interface](https://github.com/simhacker/micropolis/blob/master/micropolis-activity/src/tclx/tkucbsrc/main.c): `micropolis-activity/src/tclx/tkucbsrc/main.c`
- [Legacy Simulator](https://github.com/simhacker/micropolis/blob/master/micropolis-activity/src/sim/sim.c): `micropolis-activity/src/sim/sim.c`
- [Activity Shell](https://github.com/simhacker/micropolis/blob/master/micropolis-activity/micropolisactivity.py): `micropolis-activity/micropolisactivity.py`

### Other components

- **Player**

## Connections

- Player → GTK Frontend: opens
- GTK Frontend → GTK Views: starts
- GTK Views → Python Engine: uses
- Python Engine → City Zones: creates zones (evidence: `MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisgenericengine.py`)
- Python Engine → Tile Renderer: renders tiles
- Python Engine → City Engine: extends engine
- Python Engine → City Robots: simulates robots (evidence: `MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisgenericengine.py`)
- City Zones → City Robots: uses tools (evidence: `MicropolisCore/src/pyMicropolis/micropolisEngine/micropoliszone.py`)
- Player → Cell Interface: interacts
- Cell Interface → Cell Automata: controls
- Player → Web Client: plays
- Web Client → Web Controller: sends commands
- Web Controller → Web Game Engine: creates sessions (evidence: `turbogears/micropolis/controllers.py`)
- Web Game Engine → Python Engine: inherits (evidence: `MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisturbogearsengine.py`)
- Web Game Engine → City Robots: uses (evidence: `MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisturbogearsengine.py`)
- Web Controller → City Persistence: queries (evidence: `turbogears/micropolis/controllers.py`)
- Web Game Engine → City Persistence: uses persistence (evidence: `MicropolisCore/src/pyMicropolis/micropolisEngine/micropolisturbogearsengine.py`)
- Player → Desktop Entry: launches (evidence: `micropolis-java/src/micropolisj/Main.java`)
- Desktop Entry → Desktop Window: opens window (evidence: `micropolis-java/src/micropolisj/Main.java`)
- Desktop Window → Java Simulation: uses (evidence: `micropolis-java/src/micropolisj/gui/MainWindow.java`)
- Player → Activity Shell: starts activity
- Activity Shell → Tcl/Tk Interface: launches
- Tcl/Tk Interface → Legacy Simulator: drives simulation
