# hexianweb/cubecity architecture

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

- Interactive diagram: https://gitdiagram.com/hexianweb/cubecity
- Repository: https://github.com/hexianweb/cubecity

## Overview

CubeCity is a Vue and Three.js city-building simulation. Players inspect the city, choose a mode, and place, relocate, upgrade, or demolish buildings; the game state tracks resources and city conditions, while the 3D scene visualizes the map. The README also documents local progress storage, RCI/ESG planning, building income, and rotating building-status indicators. UI composition and several runtime links are supported by the source index; some deeper scene and simulation connections are not shown in excerpts.

Main entry points: [`src/stores/useGameState.js`](https://github.com/hexianweb/cubecity/blob/big-simcity/src/stores/useGameState.js) (Game state), [`src/App.vue`](https://github.com/hexianweb/cubecity/blob/big-simcity/src/App.vue) (App shell), [`src/js/experience.js`](https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/experience.js) (Scene runtime), [`src/js/tools/interactor/handlers.js`](https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/tools/interactor/handlers.js) (Mode handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Game interface"]
  node_app["App shell<br/>[App.vue]"]
  node_topbar["City controls<br/>[TopBar.vue]"]
  node_sidebar["Building catalog"]
  node_canvas["Game canvas<br/>[GameCanvas.vue]"]
  node_details["Building details"]
  node_dashboard["City dashboard"]
  node_dialogs["Action dialogs<br/>[DialogLayer.vue]"]
  node_guide["Player guide<br/>[GuideModal.vue]"]
end

subgraph group_simulation["City simulation"]
  node_state["Game state<br/>[useGameState.js]"]
  node_transactions["Building transactions<br/>[useBuilding.js]"]
  node_interactor["Mode handlers<br/>[handlers.js]"]
  node_interactionutils["Placement rules<br/>[utils.js]"]
end

subgraph group_runtime["3D runtime"]
  node_experience["Scene runtime<br/>[experience.js]"]
  node_world["World simulation<br/>[world.js]"]
  node_camera["Camera<br/>[camera.js]"]
  node_resources["Scene resources<br/>[resources.js]"]
end

subgraph group_domain["Game rules"]
  node_catalog["Building definitions<br/>[constants.js]"]
  node_buildings["Building behavior<br/>[building.js]"]
  node_interactionrules["Building effects"]
end

node_player(("Player"))
node_browserstorage[("Local storage")]

node_player -->|"plays through"| node_app
node_app -->|"renders"| node_topbar
node_app -->|"renders"| node_sidebar
node_app -->|"renders"| node_canvas
node_app -->|"renders"| node_details
node_app -->|"renders"| node_dashboard
node_app -->|"renders"| node_dialogs
node_topbar -->|"opens"| node_guide
node_topbar -->|"reads and updates"| node_state
node_sidebar -->|"reads"| node_state
node_details -->|"reads"| node_state
node_dashboard -->|"reads"| node_state
node_canvas -->|"creates"| node_experience
node_dialogs -->|"calls"| node_transactions
node_dialogs -->|"signals actions"| node_state
node_transactions -->|"updates"| node_state
node_state -->|"calculates effects with"| node_interactionrules
node_interactor -->|"calls placement helpers"| node_interactionutils
node_interactor -->|"updates tiles"| node_state
node_interactor -->|"updates roads"| node_world
node_interactionutils -->|"uses definitions"| node_catalog
node_buildings -->|"checks status effects"| node_interactionrules
node_experience -->|"gets game state"| node_state
node_experience -->|"creates and updates"| node_world
node_experience -->|"creates and updates"| node_camera
node_experience -->|"loads"| node_resources
node_state -->|"persists progress"| node_browserstorage

click node_app "https://github.com/hexianweb/cubecity/blob/big-simcity/src/App.vue"
click node_topbar "https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/TopBar.vue"
click node_sidebar "https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/BuildingSidebar.vue"
click node_canvas "https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/GameCanvas.vue"
click node_details "https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/BuildingDetails.vue"
click node_dashboard "https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/DashboardFooter.vue"
click node_dialogs "https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/layers/DialogLayer.vue"
click node_guide "https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/GuideModal.vue"
click node_state "https://github.com/hexianweb/cubecity/blob/big-simcity/src/stores/useGameState.js"
click node_transactions "https://github.com/hexianweb/cubecity/blob/big-simcity/src/hooks/useBuilding.js"
click node_interactor "https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/tools/interactor/handlers.js"
click node_interactionutils "https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/tools/interactor/utils.js"
click node_catalog "https://github.com/hexianweb/cubecity/blob/big-simcity/src/constants/constants.js"
click node_buildings "https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/components/tiles/building.js"
click node_interactionrules "https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/utils/building-interaction-utils.js"
click node_experience "https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/experience.js"
click node_world "https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/world/world.js"
click node_camera "https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/camera.js"
click node_resources "https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/utils/resources.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_app,node_topbar,node_sidebar,node_canvas,node_details,node_dashboard,node_dialogs,node_guide toneBlue
class node_state,node_transactions,node_interactor,node_interactionutils,node_browserstorage toneAmber
class node_experience,node_world,node_camera,node_resources toneMint
class node_catalog,node_buildings,node_interactionrules toneRose
class node_player toneIndigo
```

## Components

### Game interface

- [App shell](https://github.com/hexianweb/cubecity/blob/big-simcity/src/App.vue): `src/App.vue`
- [City controls](https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/TopBar.vue): `src/components/TopBar.vue`
- [Building catalog](https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/BuildingSidebar.vue): `src/components/BuildingSidebar.vue`
- [Game canvas](https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/GameCanvas.vue): `src/components/GameCanvas.vue`
- [Building details](https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/BuildingDetails.vue): `src/components/BuildingDetails.vue`
- [City dashboard](https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/DashboardFooter.vue): `src/components/DashboardFooter.vue`
- [Action dialogs](https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/layers/DialogLayer.vue): `src/components/layers/DialogLayer.vue`
- [Player guide](https://github.com/hexianweb/cubecity/blob/big-simcity/src/components/GuideModal.vue): `src/components/GuideModal.vue`

### City simulation

- [Game state](https://github.com/hexianweb/cubecity/blob/big-simcity/src/stores/useGameState.js): `src/stores/useGameState.js`
- [Building transactions](https://github.com/hexianweb/cubecity/blob/big-simcity/src/hooks/useBuilding.js): `src/hooks/useBuilding.js`
- [Mode handlers](https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/tools/interactor/handlers.js): `src/js/tools/interactor/handlers.js`
- [Placement rules](https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/tools/interactor/utils.js): `src/js/tools/interactor/utils.js`

### 3D runtime

- [Scene runtime](https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/experience.js): `src/js/experience.js`
- [World simulation](https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/world/world.js): `src/js/world/world.js`
- [Camera](https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/camera.js): `src/js/camera.js`
- [Scene resources](https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/utils/resources.js): `src/js/utils/resources.js`

### Game rules

- [Building definitions](https://github.com/hexianweb/cubecity/blob/big-simcity/src/constants/constants.js): `src/constants/constants.js`
- [Building behavior](https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/components/tiles/building.js): `src/js/components/tiles/building.js`
- [Building effects](https://github.com/hexianweb/cubecity/blob/big-simcity/src/js/utils/building-interaction-utils.js): `src/js/utils/building-interaction-utils.js`

### Other components

- **Player**
- **Local storage**

## Connections

- Player → App shell: plays through (evidence: `README.md`)
- App shell → City controls: renders (evidence: `src/App.vue`)
- App shell → Building catalog: renders (evidence: `src/App.vue`)
- App shell → Game canvas: renders (evidence: `src/App.vue`)
- App shell → Building details: renders (evidence: `src/App.vue`)
- App shell → City dashboard: renders (evidence: `src/App.vue`)
- App shell → Action dialogs: renders (evidence: `src/App.vue`)
- City controls → Player guide: opens (evidence: `src/components/TopBar.vue`)
- City controls → Game state: reads and updates (evidence: `src/components/TopBar.vue`)
- Building catalog → Game state: reads (evidence: `src/components/BuildingSidebar.vue`)
- Building details → Game state: reads (evidence: `src/components/BuildingDetails.vue`)
- City dashboard → Game state: reads (evidence: `src/components/DashboardFooter.vue`)
- Game canvas → Scene runtime: creates (evidence: `src/components/GameCanvas.vue`)
- Action dialogs → Building transactions: calls (evidence: `src/components/layers/DialogLayer.vue`)
- Action dialogs → Game state: signals actions (evidence: `src/components/layers/DialogLayer.vue`)
- Building transactions → Game state: updates (evidence: `src/hooks/useBuilding.js`)
- Game state → Building effects: calculates effects with (evidence: `src/stores/useGameState.js`)
- Mode handlers → Placement rules: calls placement helpers (evidence: `src/js/tools/interactor/handlers.js`)
- Mode handlers → Game state: updates tiles (evidence: `src/js/tools/interactor/handlers.js`)
- Mode handlers → World simulation: updates roads (evidence: `src/js/tools/interactor/handlers.js`)
- Placement rules → Building definitions: uses definitions (evidence: `src/js/tools/interactor/utils.js`)
- Building behavior → Building effects: checks status effects (evidence: `src/js/components/tiles/building.js`)
- Scene runtime → Game state: gets game state (evidence: `src/js/experience.js`)
- Scene runtime → World simulation: creates and updates (evidence: `src/js/experience.js`)
- Scene runtime → Camera: creates and updates (evidence: `src/js/experience.js`)
- Scene runtime → Scene resources: loads (evidence: `src/js/experience.js`)
- Game state → Local storage: persists progress (evidence: `README.md`)
