# d1nary/city_sim architecture

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

- Interactive diagram: https://gitdiagram.com/d1nary/city_sim
- Repository: https://github.com/d1nary/city_sim

## Overview

1. This is a native C++ simulation project built with CMake. The source tree is organized as a small engine plus game/domain layer, and the build artifacts show a compiled executable named `city_sim`. The repository also vendors GLFW through CMake’s `_deps`, so there is at least a window/input layer dependency for the desktop runtime.

2. The highest-level runtime entry point is `src/main.cpp`, which likely boots `core::Application`. `application` appears to own the main loop and coordinate the major subsystems rather than letting them talk to each other directly.

3. The `core` subsystem is the cross-cutting foundation. `time` suggests simulation timing or fixed-step update support, while `config.hpp` likely centralizes tunable constants. This is the layer other systems should depend on, not the reverse.

4. The world model lives under `src/world` and is split into `World`, `Grid`, and `Tile`. That indicates a tile/grid-based simulation space where `World` owns the map state, `Grid` provides spatial indexing or layout, and `Tile` is the atomic cell used by rendering, pathing, or placement logic.

5. Entities are managed separately from the world geometry in `src/entities`. `Entity` is the base abstraction, `Npc` is a concrete simulated actor, and `EntityManager` owns lifecycle and update iteration. This is the main gameplay-state boundary for movable agents.

6. Behavior is factored out into `src/behaviors` via an `IBehavior` interface and concrete `WanderBehavior` and `WorkBehavior` implementations. This suggests a behavior-driven NPC system where entities delegate decision-making to interchangeable behaviors instead of hard-coding logic into `Npc`.

7. Buildings are another domain subsystem under `src/buildings`. `Building` is the shared base, `House` is a concrete building type, and `BuildingManager` owns placement or lifecycle management. This is likely tied to the world grid and to NPC behavior, especially the work/home relationship.

8. The renderer is isolated in `src/renderer` and contains `renderer`, `camera`, and `DebugUI`. This implies a dedicated visualization layer with a movable view and an overlay for inspecting simulation state. The renderer probably consumes world/entity/building state but does not own it.

9. The main data flow is probably: application initializes core timing, world, managers, and renderer; the simulation updates entities and buildings against the world grid; then the renderer reads the resulting state each frame and draws it through the camera. The debug UI sits alongside rendering as an inspection/control layer.

10. The main architectural boundary is between simulation state and presentation. World/entities/buildings/behaviors are the model and update logic; renderer/camera/DebugUI are the view and diagnostics. That separation is what to preserve in an architecture diagram.

11. From the file naming, this looks like an object-oriented, single-process desktop simulation rather than a client-server or data-pipeline system. The important external dependency is GLFW for windowing/input; everything else appears to be internal C++ modules built into one executable.

Main entry points: [`src/core/application.cpp`](https://github.com/d1nary/city_sim/blob/main/src/core/application.cpp) (Application), [`src/renderer/renderer.cpp`](https://github.com/d1nary/city_sim/blob/main/src/renderer/renderer.cpp) (Renderer), [`src/buildings/BuildingManager.cpp`](https://github.com/d1nary/city_sim/blob/main/src/buildings/BuildingManager.cpp) (BuildingManager), [`src/world/world.cpp`](https://github.com/d1nary/city_sim/blob/main/src/world/world.cpp) (World)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["main<br/>entry point<br/>[main.cpp]"]
  node_application["Application<br/>orchestrator<br/>[application.cpp]"]
end

subgraph group_core["Core"]
  node_config["Config<br/>settings<br/>[config.hpp]"]
  node_time["Time<br/>simulation timing<br/>[time.cpp]"]
end

subgraph group_simulation["Simulation"]
  node_world["World<br/>[world.cpp]"]
  node_grid["Grid<br/>[grid.cpp]"]
  node_tile{{"Tile<br/>cell model<br/>[tile.hpp]"}}
  node_entities["EntityManager<br/>entity lifecycle<br/>[EntityManager.cpp]"]
  node_entity["Entity<br/>base actor<br/>[entity.cpp]"]
  node_npc(("Npc<br/>agent<br/>[npc.cpp]"))
  node_behaviors["IBehavior<br/>behavior interface<br/>[IBehavior.hpp]"]
  node_wander["Wander<br/>behavior<br/>[WanderBehavior.cpp]"]
  node_work["Work<br/>behavior<br/>[WorkBehavior.cpp]"]
  node_buildings["BuildingManager<br/>building lifecycle"]
  node_building["Building<br/>structure base<br/>[building.cpp]"]
  node_house(("House<br/>structure<br/>[house.cpp]"))
end

subgraph group_presentation["Presentation"]
  node_renderer["Renderer<br/>rendering<br/>[renderer.cpp]"]
  node_camera["Camera<br/>view control<br/>[camera.cpp]"]
  node_debugui["DebugUI<br/>inspection overlay<br/>[DebugUI.cpp]"]
end

subgraph group_external["External"]
  node_glfw["GLFW<br/>window/input lib<br/>[glfw3Config.cmake]"]
end

node_main -->|"starts"| node_application
node_application -->|"ticks"| node_time
node_application -->|"owns"| node_world
node_application -->|"updates"| node_entities
node_application -->|"updates"| node_buildings
node_application -->|"drives"| node_renderer
node_application -->|"reads"| node_config
node_application -.->|"uses"| node_glfw
node_world -->|"contains"| node_grid
node_grid -->|"stores"| node_tile
node_entities -->|"manages"| node_entity
node_entity -->|"specializes"| node_npc
node_npc -->|"delegates"| node_behaviors
node_behaviors -->|"implements"| node_wander
node_behaviors -->|"implements"| node_work
node_buildings -->|"manages"| node_building
node_building -->|"specializes"| node_house
node_renderer -->|"uses"| node_camera
node_renderer -->|"overlays"| node_debugui
node_renderer -->|"reads"| node_world
node_renderer -->|"reads"| node_entities
node_renderer -->|"reads"| node_buildings
node_buildings -->|"places in"| node_world
node_entities -->|"operates in"| node_world
node_npc -.->|"interacts with"| node_buildings

click node_main "https://github.com/d1nary/city_sim/blob/main/src/main.cpp"
click node_application "https://github.com/d1nary/city_sim/blob/main/src/core/application.cpp"
click node_config "https://github.com/d1nary/city_sim/blob/main/src/core/config.hpp"
click node_time "https://github.com/d1nary/city_sim/blob/main/src/core/time.cpp"
click node_world "https://github.com/d1nary/city_sim/blob/main/src/world/world.cpp"
click node_grid "https://github.com/d1nary/city_sim/blob/main/src/world/grid.cpp"
click node_tile "https://github.com/d1nary/city_sim/blob/main/src/world/tile.hpp"
click node_entities "https://github.com/d1nary/city_sim/blob/main/src/entities/EntityManager.cpp"
click node_entity "https://github.com/d1nary/city_sim/blob/main/src/entities/entity.cpp"
click node_npc "https://github.com/d1nary/city_sim/blob/main/src/entities/npc.cpp"
click node_behaviors "https://github.com/d1nary/city_sim/blob/main/src/behaviors/IBehavior.hpp"
click node_wander "https://github.com/d1nary/city_sim/blob/main/src/behaviors/WanderBehavior.cpp"
click node_work "https://github.com/d1nary/city_sim/blob/main/src/behaviors/WorkBehavior.cpp"
click node_buildings "https://github.com/d1nary/city_sim/blob/main/src/buildings/BuildingManager.cpp"
click node_building "https://github.com/d1nary/city_sim/blob/main/src/buildings/building.cpp"
click node_house "https://github.com/d1nary/city_sim/blob/main/src/buildings/house.cpp"
click node_renderer "https://github.com/d1nary/city_sim/blob/main/src/renderer/renderer.cpp"
click node_camera "https://github.com/d1nary/city_sim/blob/main/src/renderer/camera.cpp"
click node_debugui "https://github.com/d1nary/city_sim/blob/main/src/renderer/DebugUI.cpp"
click node_glfw "https://github.com/d1nary/city_sim/blob/main/build/_deps/glfw-build/src/glfw3Config.cmake"

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_main,node_application toneBlue
class node_config,node_time toneAmber
class node_world,node_grid,node_tile,node_entities,node_entity,node_npc,node_behaviors,node_wander,node_work,node_buildings,node_building,node_house toneMint
class node_renderer,node_camera,node_debugui toneRose
class node_glfw toneIndigo
```

## Components

### Runtime

Program entry and orchestration

- [main](https://github.com/d1nary/city_sim/blob/main/src/main.cpp): entry point · Program startup and handoff to the application · `src/main.cpp`
- [Application](https://github.com/d1nary/city_sim/blob/main/src/core/application.cpp): orchestrator · Owns initialization and the main loop · `src/core/application.cpp`

### Core

Shared simulation foundation

- [Config](https://github.com/d1nary/city_sim/blob/main/src/core/config.hpp): settings · Central tunable constants · `src/core/config.hpp`
- [Time](https://github.com/d1nary/city_sim/blob/main/src/core/time.cpp): simulation timing · Frame or fixed-step timing support · `src/core/time.cpp`

### Simulation

World state and gameplay logic

- [World](https://github.com/d1nary/city_sim/blob/main/src/world/world.cpp): simulation world · Owns the overall map and simulation space · `src/world/world.cpp`
- [Grid](https://github.com/d1nary/city_sim/blob/main/src/world/grid.cpp): spatial grid · Tile layout and spatial indexing · `src/world/grid.cpp`
- [Tile](https://github.com/d1nary/city_sim/blob/main/src/world/tile.hpp): cell model · Atomic world cell used by simulation logic · `src/world/tile.hpp`
- [EntityManager](https://github.com/d1nary/city_sim/blob/main/src/entities/EntityManager.cpp): entity lifecycle · Owns entity update and lifetime management · `src/entities/EntityManager.cpp`
- [Entity](https://github.com/d1nary/city_sim/blob/main/src/entities/entity.cpp): base actor · Shared abstraction for simulated actors · `src/entities/entity.cpp`
- [Npc](https://github.com/d1nary/city_sim/blob/main/src/entities/npc.cpp): agent · Concrete simulated character · `src/entities/npc.cpp`
- [IBehavior](https://github.com/d1nary/city_sim/blob/main/src/behaviors/IBehavior.hpp): behavior interface · Pluggable decision-making contract · `src/behaviors/IBehavior.hpp`
- [Wander](https://github.com/d1nary/city_sim/blob/main/src/behaviors/WanderBehavior.cpp): behavior · Idle or roaming NPC behavior · `src/behaviors/WanderBehavior.cpp`
- [Work](https://github.com/d1nary/city_sim/blob/main/src/behaviors/WorkBehavior.cpp): behavior · Task-oriented NPC behavior · `src/behaviors/WorkBehavior.cpp`
- [BuildingManager](https://github.com/d1nary/city_sim/blob/main/src/buildings/BuildingManager.cpp): building lifecycle · Owns building placement and update flow · `src/buildings/BuildingManager.cpp`
- [Building](https://github.com/d1nary/city_sim/blob/main/src/buildings/building.cpp): structure base · Shared abstraction for constructed structures · `src/buildings/building.cpp`
- [House](https://github.com/d1nary/city_sim/blob/main/src/buildings/house.cpp): structure · Concrete residential building · `src/buildings/house.cpp`

### Presentation

Rendering and diagnostics

- [Renderer](https://github.com/d1nary/city_sim/blob/main/src/renderer/renderer.cpp): rendering · Draws simulation state to the screen · `src/renderer/renderer.cpp`
- [Camera](https://github.com/d1nary/city_sim/blob/main/src/renderer/camera.cpp): view control · Controls the visible region of the world · `src/renderer/camera.cpp`
- [DebugUI](https://github.com/d1nary/city_sim/blob/main/src/renderer/DebugUI.cpp): inspection overlay · Runtime diagnostics and inspection controls · `src/renderer/DebugUI.cpp`

### External

Third-party runtime dependency

- [GLFW](https://github.com/d1nary/city_sim/blob/main/build/_deps/glfw-build/src/glfw3Config.cmake): window/input lib · External desktop windowing and input dependency · `build/_deps/glfw-build/src/glfw3Config.cmake`

## Connections

- main → Application: starts · Main hands control to application startup
- Application → Time: ticks · Application drives simulation timing
- Application → World: owns · Application coordinates world state
- Application → EntityManager: updates · Application advances entity manager each frame
- Application → BuildingManager: updates · Application advances building manager each frame
- Application → Renderer: drives · Application triggers rendering after simulation update
- Application → Config: reads · Application uses shared configuration
- Application → GLFW: uses · Desktop runtime depends on GLFW for windowing and input
- World → Grid: contains · World owns spatial layout
- Grid → Tile: stores · Grid is composed of tiles
- EntityManager → Entity: manages · Manager owns entity lifecycle
- Entity → Npc: specializes · NPC is a concrete entity type
- Npc → IBehavior: delegates · NPC behavior is driven through the interface
- IBehavior → Wander: implements · Wander behavior is one implementation
- IBehavior → Work: implements · Work behavior is one implementation
- BuildingManager → Building: manages · Manager owns building lifecycle
- Building → House: specializes · House is a concrete building type
- Renderer → Camera: uses · Renderer uses camera for framing
- Renderer → DebugUI: overlays · Debug UI is shown alongside rendering
- Renderer → World: reads · Renderer consumes world state
- Renderer → EntityManager: reads · Renderer consumes entity state
- Renderer → BuildingManager: reads · Renderer consumes building state
- BuildingManager → World: places in · Buildings are positioned against world grid
- EntityManager → World: operates in · Entities update within the world context
- Npc → BuildingManager: interacts with · NPC behavior may depend on buildings such as homes or work sites
