# azgaar/fantasy-map-generator architecture

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

- Interactive diagram: https://gitdiagram.com/azgaar/fantasy-map-generator
- Repository: https://github.com/azgaar/fantasy-map-generator

## Overview

#### Purpose and Runtime
Azgaar’s Fantasy Map Generator is a client-side web application for procedurally creating and interactively editing fantasy maps. It is transitioning from legacy JavaScript toward TypeScript while preserving `.map` compatibility. The browser app is served as static assets, with Vite development/build configuration in `vite.config.ts`; deployment can use Netlify/Docker via `netlify.toml`, `Dockerfile`, and `.docker/default.conf`.

#### Entry and Application Shell
The primary document is `src/index.html`; application bootstrapping is split between `main.js` and `public/main.js`. App-level initialization, installation/PWA concerns, fonts, and lifecycle services are centralized in `src/services/app-shell.ts`, `src/services/installation.ts`, and `public/sw.js`. The UI is primarily SVG/DOM-driven, with an optional 3D/WebGL visualization path.

#### World State and Data Model Boundary
The intended architecture keeps world data passive: generators and editors own behavior, while renderers consume state. The packed spatial graph is a core representation (`src/types/PackedGraph.ts`), supporting cell-based terrain and political/economic entities. Data-model contracts and migration intent are documented in `docs/architecture/data_model.md`, `docs/architecture/future_data_model.md`, and `docs/architecture/migration_guide.md`.

#### Procedural Generation Pipeline
Generation begins from settings and terrain/heightmap creation, then derives geographic and societal layers. Core stages include Voronoi graph construction (`src/generators/voronoi.ts`), terrain creation (`src/generators/heightmap-generator.ts`), biomes and hydrology (`src/generators/biomes-generator.ts`, `src/generators/river-generator.ts`), settlements/states (`src/generators/burgs-generator.ts`, `src/generators/states-generator.ts`), and routes/economy (`src/generators/routes-generator.ts`, `src/generators/goods-generator.ts`). The domain sequencing is further specified in `docs/domain/generation_pipeline.md`.

#### Editing and Controller Layer
Interactive map tools are controller modules that perform controlled world-state mutations and then request redraws. This layer covers terrain and geographic editing (`src/controllers/heightmap-editor.ts`, `src/controllers/river-editor.ts`), political entities (`src/controllers/states-editor.ts`, `src/controllers/burg-editor.ts`), and map infrastructure/economy (`src/controllers/route-editor.ts`, `src/controllers/goods-editor.ts`). Controller registration is consolidated in `src/controllers/index.ts`; shared interaction primitives live under `src/components/`.

#### Rendering and Visualization
Renderers transform world state into visual layers and should not mutate it. Geographic SVG layers are handled by modules such as `src/renderers/draw-heightmap.ts`, `src/renderers/draw-biomes.ts`, and `src/renderers/draw-borders.ts`; labels and symbols have specialized rendering subsystems in `src/renderers/labels/labels-renderer.ts` and `src/renderers/emblems/renderer.ts`. `src/renderers/viewport/viewport-renderer.ts` coordinates viewport drawing, while `src/renderers/view-3d-renderer.ts` supports the separate 3D path.

#### Persistence, Import/Export, and External Boundaries
Map files are loaded, migrated, and saved through `src/services/io/load.ts`, `src/services/io/save.ts`, and `src/services/io/export.ts`; autosave is in `src/services/autosave.ts`. Browser-local persistence is supported by bundled IndexedDB code at `public/libs/indexedDB.js`. Cloud-facing behavior is isolated in `src/services/io/cloud.ts`; version/update handling is in `src/services/io/auto-update.ts` and `src/services/versioning.ts`. Static assets, style presets, heightmaps, and third-party browser libraries are served from `public/`.

Main entry points: [`src/types/PackedGraph.ts`](https://github.com/azgaar/fantasy-map-generator/blob/master/src/types/PackedGraph.ts) (Packed world state), [`src/renderers/viewport/viewport-renderer.ts`](https://github.com/azgaar/fantasy-map-generator/blob/master/src/renderers/viewport/viewport-renderer.ts) (Viewport renderer), [`src/services/io/load.ts`](https://github.com/azgaar/fantasy-map-generator/blob/master/src/services/io/load.ts) (Map load, save, export), [`src/generators/voronoi.ts`](https://github.com/azgaar/fantasy-map-generator/blob/master/src/generators/voronoi.ts) (Voronoi graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Browser Runtime"]
  node_document["HTML document<br/>entry document<br/>[index.html]"]
  node_bootstrap["Application bootstrap<br/>browser entry<br/>[main.js]"]
  node_app_shell["App shell<br/>lifecycle service<br/>[app-shell.ts]"]
  node_service_worker["Service worker<br/>PWA worker<br/>[sw.js]"]
  node_world_state[("Packed world state<br/>spatial data model<br/>[PackedGraph.ts]")]
end

subgraph group_generation["Generation Pipeline"]
  node_generation_spec["Generation sequencing<br/>domain specification"]
  node_voronoi["Voronoi graph<br/>generator stage<br/>[voronoi.ts]"]
  node_terrain["Terrain and heightmap<br/>generator stage"]
  node_geography["Biomes and rivers<br/>generator stages"]
  node_society["Burgs and states<br/>generator stages<br/>[burgs-generator.ts]"]
  node_economy["Routes and goods<br/>generator stages"]
end

subgraph group_editing["Editing"]
  node_controllers["Editor controllers<br/>interaction registry<br/>[index.ts]"]
  node_components["Interaction components<br/>UI primitives"]
end

subgraph group_rendering["Rendering"]
  node_viewport["Viewport renderer<br/>render coordinator"]
  node_svg_layers["Geographic SVG layers<br/>renderer modules<br/>[draw-heightmap.ts]"]
  node_annotations["Labels and emblems<br/>specialized renderers<br/>[labels-renderer.ts]"]
  node_view_3d["3D visualization<br/>WebGL renderer"]
end

subgraph group_persistence["Persistence &amp; External I/O"]
  node_map_io["Map load, save, export<br/>file I/O service<br/>[load.ts]"]
  node_autosave["Autosave<br/>persistence service<br/>[autosave.ts]"]
  node_local_db[("Browser IndexedDB<br/>local storage<br/>[indexedDB.js]")]
  node_cloud_io["Cloud I/O<br/>external integration<br/>[cloud.ts]"]
end

node_document -->|"loads"| node_bootstrap
node_bootstrap -->|"initializes"| node_app_shell
node_app_shell -.->|"registers"| node_service_worker
node_voronoi -->|"provides cells"| node_terrain
node_terrain -->|"derives"| node_geography
node_geography -->|"shapes"| node_society
node_society -->|"enables"| node_economy
node_generation_spec -.->|"specifies order"| node_voronoi
node_voronoi -->|"builds"| node_world_state
node_terrain -->|"writes terrain"| node_world_state
node_geography -->|"writes geography"| node_world_state
node_society -->|"writes entities"| node_world_state
node_economy -->|"writes routes and goods"| node_world_state
node_components -->|"drives tools"| node_controllers
node_controllers -->|"mutates"| node_world_state
node_controllers -->|"requests redraw"| node_viewport
node_world_state -->|"render input"| node_viewport
node_viewport -->|"coordinates"| node_svg_layers
node_viewport -->|"coordinates"| node_annotations
node_world_state -->|"render input"| node_view_3d
node_world_state -->|"load/save state"| node_map_io
node_autosave -->|"saves through"| node_map_io
node_map_io -->|"persists locally"| node_local_db
node_map_io -.->|"cloud operations"| node_cloud_io

click node_document "https://github.com/azgaar/fantasy-map-generator/blob/master/src/index.html"
click node_bootstrap "https://github.com/azgaar/fantasy-map-generator/blob/master/main.js"
click node_app_shell "https://github.com/azgaar/fantasy-map-generator/blob/master/src/services/app-shell.ts"
click node_service_worker "https://github.com/azgaar/fantasy-map-generator/blob/master/public/sw.js"
click node_world_state "https://github.com/azgaar/fantasy-map-generator/blob/master/src/types/PackedGraph.ts"
click node_generation_spec "https://github.com/azgaar/fantasy-map-generator/blob/master/docs/domain/generation_pipeline.md"
click node_voronoi "https://github.com/azgaar/fantasy-map-generator/blob/master/src/generators/voronoi.ts"
click node_terrain "https://github.com/azgaar/fantasy-map-generator/blob/master/src/generators/heightmap-generator.ts"
click node_geography "https://github.com/azgaar/fantasy-map-generator/blob/master/src/generators/biomes-generator.ts"
click node_society "https://github.com/azgaar/fantasy-map-generator/blob/master/src/generators/burgs-generator.ts"
click node_economy "https://github.com/azgaar/fantasy-map-generator/blob/master/src/generators/routes-generator.ts"
click node_controllers "https://github.com/azgaar/fantasy-map-generator/blob/master/src/controllers/index.ts"
click node_viewport "https://github.com/azgaar/fantasy-map-generator/blob/master/src/renderers/viewport/viewport-renderer.ts"
click node_svg_layers "https://github.com/azgaar/fantasy-map-generator/blob/master/src/renderers/draw-heightmap.ts"
click node_annotations "https://github.com/azgaar/fantasy-map-generator/blob/master/src/renderers/labels/labels-renderer.ts"
click node_view_3d "https://github.com/azgaar/fantasy-map-generator/blob/master/src/renderers/view-3d-renderer.ts"
click node_map_io "https://github.com/azgaar/fantasy-map-generator/blob/master/src/services/io/load.ts"
click node_autosave "https://github.com/azgaar/fantasy-map-generator/blob/master/src/services/autosave.ts"
click node_local_db "https://github.com/azgaar/fantasy-map-generator/blob/master/public/libs/indexedDB.js"
click node_cloud_io "https://github.com/azgaar/fantasy-map-generator/blob/master/src/services/io/cloud.ts"

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_document,node_bootstrap,node_app_shell,node_service_worker,node_world_state toneBlue
class node_generation_spec,node_voronoi,node_terrain,node_geography,node_society,node_economy toneAmber
class node_controllers,node_components toneMint
class node_viewport,node_svg_layers,node_annotations,node_view_3d toneRose
class node_map_io,node_autosave,node_local_db,node_cloud_io toneIndigo
```

## Components

### Browser Runtime

- [HTML document](https://github.com/azgaar/fantasy-map-generator/blob/master/src/index.html): entry document · `src/index.html`
- [Application bootstrap](https://github.com/azgaar/fantasy-map-generator/blob/master/main.js): browser entry · `main.js`
- [App shell](https://github.com/azgaar/fantasy-map-generator/blob/master/src/services/app-shell.ts): lifecycle service · Initializes application services, fonts, and installation concerns. · `src/services/app-shell.ts`
- [Service worker](https://github.com/azgaar/fantasy-map-generator/blob/master/public/sw.js): PWA worker · `public/sw.js`
- [Packed world state](https://github.com/azgaar/fantasy-map-generator/blob/master/src/types/PackedGraph.ts): spatial data model · Passive cell graph and map entities shared across features. · `src/types/PackedGraph.ts`

### Generation Pipeline

- [Generation sequencing](https://github.com/azgaar/fantasy-map-generator/blob/master/docs/domain/generation_pipeline.md): domain specification · `docs/domain/generation_pipeline.md`
- [Voronoi graph](https://github.com/azgaar/fantasy-map-generator/blob/master/src/generators/voronoi.ts): generator stage · `src/generators/voronoi.ts`
- [Terrain and heightmap](https://github.com/azgaar/fantasy-map-generator/blob/master/src/generators/heightmap-generator.ts): generator stage · `src/generators/heightmap-generator.ts`
- [Biomes and rivers](https://github.com/azgaar/fantasy-map-generator/blob/master/src/generators/biomes-generator.ts): generator stages · `src/generators/biomes-generator.ts`
- [Burgs and states](https://github.com/azgaar/fantasy-map-generator/blob/master/src/generators/burgs-generator.ts): generator stages · `src/generators/burgs-generator.ts`
- [Routes and goods](https://github.com/azgaar/fantasy-map-generator/blob/master/src/generators/routes-generator.ts): generator stages · `src/generators/routes-generator.ts`

### Editing

- [Editor controllers](https://github.com/azgaar/fantasy-map-generator/blob/master/src/controllers/index.ts): interaction registry · Controlled mutations for terrain, entities, routes, and goods. · `src/controllers/index.ts`
- **Interaction components**: UI primitives

### Rendering

- [Viewport renderer](https://github.com/azgaar/fantasy-map-generator/blob/master/src/renderers/viewport/viewport-renderer.ts): render coordinator · `src/renderers/viewport/viewport-renderer.ts`
- [Geographic SVG layers](https://github.com/azgaar/fantasy-map-generator/blob/master/src/renderers/draw-heightmap.ts): renderer modules · `src/renderers/draw-heightmap.ts`
- [Labels and emblems](https://github.com/azgaar/fantasy-map-generator/blob/master/src/renderers/labels/labels-renderer.ts): specialized renderers · `src/renderers/labels/labels-renderer.ts`
- [3D visualization](https://github.com/azgaar/fantasy-map-generator/blob/master/src/renderers/view-3d-renderer.ts): WebGL renderer · `src/renderers/view-3d-renderer.ts`

### Persistence & External I/O

- [Map load, save, export](https://github.com/azgaar/fantasy-map-generator/blob/master/src/services/io/load.ts): file I/O service · Loads and migrates compatible map files, then saves or exports them. · `src/services/io/load.ts`
- [Autosave](https://github.com/azgaar/fantasy-map-generator/blob/master/src/services/autosave.ts): persistence service · `src/services/autosave.ts`
- [Browser IndexedDB](https://github.com/azgaar/fantasy-map-generator/blob/master/public/libs/indexedDB.js): local storage · `public/libs/indexedDB.js`
- [Cloud I/O](https://github.com/azgaar/fantasy-map-generator/blob/master/src/services/io/cloud.ts): external integration · `src/services/io/cloud.ts`

## Connections

- HTML document → Application bootstrap: loads
- Application bootstrap → App shell: initializes
- App shell → Service worker: registers
- Voronoi graph → Terrain and heightmap: provides cells
- Terrain and heightmap → Biomes and rivers: derives
- Biomes and rivers → Burgs and states: shapes
- Burgs and states → Routes and goods: enables
- Generation sequencing → Voronoi graph: specifies order
- Voronoi graph → Packed world state: builds
- Terrain and heightmap → Packed world state: writes terrain
- Biomes and rivers → Packed world state: writes geography
- Burgs and states → Packed world state: writes entities
- Routes and goods → Packed world state: writes routes and goods
- Interaction components → Editor controllers: drives tools
- Editor controllers → Packed world state: mutates
- Editor controllers → Viewport renderer: requests redraw
- Packed world state → Viewport renderer: render input
- Viewport renderer → Geographic SVG layers: coordinates
- Viewport renderer → Labels and emblems: coordinates
- Packed world state → 3D visualization: render input
- Packed world state → Map load, save, export: load/save state
- Autosave → Map load, save, export: saves through
- Map load, save, export → Browser IndexedDB: persists locally
- Map load, save, export → Cloud I/O: cloud operations