# rastapasta/mapscii architecture

> Architecture diagram of the GitHub repository rastapasta/mapscii, 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/rastapasta/mapscii
- Repository: https://github.com/rastapasta/mapscii

## Overview

MapSCII renders interactive vector-tile maps in a terminal. The workflow starts with CLI options, initializes tile access and styling, fetches and parses visible tiles, transforms features into terminal drawing operations, and writes Braille or ASCII frames. Its documented local MBTiles/offline source and remote tile-server modes are represented; source excerpts do not show every input or persistence detail, so uncertain wiring is omitted.

Main entry points: [`src/TileSource.js`](https://github.com/rastapasta/mapscii/blob/master/src/TileSource.js) (Tile source), [`src/Mapscii.js`](https://github.com/rastapasta/mapscii/blob/master/src/Mapscii.js) (Map interaction), [`src/Renderer.js`](https://github.com/rastapasta/mapscii/blob/master/src/Renderer.js) (Map renderer), [`main.js`](https://github.com/rastapasta/mapscii/blob/master/main.js) (CLI startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application control"]
  node_cli["CLI startup<br/>[main.js]"]
  node_ui["Map interaction<br/>[Mapscii.js]"]
  node_config["Runtime settings<br/>[config.js]"]
end

subgraph group_tiles["Tile data"]
  node_tile_source["Tile source<br/>[TileSource.js]"]
  node_remote["Vector tile server"]
  node_mbtiles[("Local MBTiles")]
  node_tile["Tile decoding<br/>[Tile.js]"]
end

subgraph group_render["Rendering"]
  node_styler["Style rules<br/>[Styler.js]"]
  node_renderer["Map renderer<br/>[Renderer.js]"]
  node_labels["Label placement<br/>[LabelBuffer.js]"]
  node_canvas["Drawing canvas<br/>[Canvas.js]"]
  node_geometry["Map utilities<br/>[utils.js]"]
  node_styles["Style files"]
end

subgraph group_terminal["Terminal output"]
  node_braille["Braille buffer<br/>[BrailleBuffer.js]"]
  node_terminal_out["Terminal"]
end

node_user(("Map viewer"))

node_user -->|"starts"| node_cli
node_cli -->|"reads defaults"| node_config
node_cli -->|"initializes"| node_ui
node_ui -->|"uses settings"| node_config
node_ui -->|"initializes"| node_tile_source
node_ui -->|"draws map"| node_renderer
node_ui -->|"loads style"| node_styles
node_tile_source -->|"fetches tiles"| node_remote
node_tile_source -->|"reads tiles"| node_mbtiles
node_tile_source -->|"creates and loads"| node_tile
node_tile_source -->|"sets styler"| node_styler
node_tile -->|"selects styles"| node_styler
node_renderer -->|"requests tiles"| node_tile_source
node_renderer -->|"configures source"| node_styler
node_renderer -->|"places labels"| node_labels
node_renderer -->|"draws features"| node_canvas
node_renderer -->|"projects coordinates"| node_geometry
node_canvas -->|"writes pixels"| node_braille
node_braille -->|"reads display mode"| node_config
node_ui -->|"writes frames"| node_terminal_out
node_tile_source -.->|"persists downloaded tiles"| node_remote

click node_cli "https://github.com/rastapasta/mapscii/blob/master/main.js"
click node_ui "https://github.com/rastapasta/mapscii/blob/master/src/Mapscii.js"
click node_config "https://github.com/rastapasta/mapscii/blob/master/src/config.js"
click node_tile_source "https://github.com/rastapasta/mapscii/blob/master/src/TileSource.js"
click node_tile "https://github.com/rastapasta/mapscii/blob/master/src/Tile.js"
click node_styler "https://github.com/rastapasta/mapscii/blob/master/src/Styler.js"
click node_renderer "https://github.com/rastapasta/mapscii/blob/master/src/Renderer.js"
click node_labels "https://github.com/rastapasta/mapscii/blob/master/src/LabelBuffer.js"
click node_canvas "https://github.com/rastapasta/mapscii/blob/master/src/Canvas.js"
click node_braille "https://github.com/rastapasta/mapscii/blob/master/src/BrailleBuffer.js"
click node_geometry "https://github.com/rastapasta/mapscii/blob/master/src/utils.js"
click node_styles "https://github.com/rastapasta/mapscii/tree/master/styles"

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_cli,node_ui,node_config,node_user toneBlue
class node_tile_source,node_remote,node_mbtiles,node_tile toneAmber
class node_styler,node_renderer,node_labels,node_canvas,node_geometry,node_styles toneMint
class node_braille,node_terminal_out toneRose
```

## Components

### Application control

- [CLI startup](https://github.com/rastapasta/mapscii/blob/master/main.js): `main.js`
- [Map interaction](https://github.com/rastapasta/mapscii/blob/master/src/Mapscii.js): `src/Mapscii.js`
- [Runtime settings](https://github.com/rastapasta/mapscii/blob/master/src/config.js): `src/config.js`

### Tile data

- [Tile source](https://github.com/rastapasta/mapscii/blob/master/src/TileSource.js): `src/TileSource.js`
- **Vector tile server**
- **Local MBTiles**
- [Tile decoding](https://github.com/rastapasta/mapscii/blob/master/src/Tile.js): `src/Tile.js`

### Rendering

- [Style rules](https://github.com/rastapasta/mapscii/blob/master/src/Styler.js): `src/Styler.js`
- [Map renderer](https://github.com/rastapasta/mapscii/blob/master/src/Renderer.js): `src/Renderer.js`
- [Label placement](https://github.com/rastapasta/mapscii/blob/master/src/LabelBuffer.js): `src/LabelBuffer.js`
- [Drawing canvas](https://github.com/rastapasta/mapscii/blob/master/src/Canvas.js): `src/Canvas.js`
- [Map utilities](https://github.com/rastapasta/mapscii/blob/master/src/utils.js): `src/utils.js`
- [Style files](https://github.com/rastapasta/mapscii/tree/master/styles): `styles`

### Terminal output

- [Braille buffer](https://github.com/rastapasta/mapscii/blob/master/src/BrailleBuffer.js): `src/BrailleBuffer.js`
- **Terminal**

### Other components

- **Map viewer**

## Connections

- Map viewer → CLI startup: starts (evidence: `README.md`)
- CLI startup → Runtime settings: reads defaults (evidence: `main.js`)
- CLI startup → Map interaction: initializes (evidence: `main.js`)
- Map interaction → Runtime settings: uses settings (evidence: `src/Mapscii.js`)
- Map interaction → Tile source: initializes (evidence: `src/Mapscii.js`)
- Map interaction → Map renderer: draws map (evidence: `src/Mapscii.js`)
- Map interaction → Style files: loads style (evidence: `src/Mapscii.js`)
- Tile source → Vector tile server: fetches tiles (evidence: `src/TileSource.js`)
- Tile source → Local MBTiles: reads tiles (evidence: `src/TileSource.js`)
- Tile source → Tile decoding: creates and loads (evidence: `src/TileSource.js`)
- Tile source → Style rules: sets styler (evidence: `src/TileSource.js`)
- Tile decoding → Style rules: selects styles (evidence: `src/Tile.js`)
- Map renderer → Tile source: requests tiles (evidence: `src/Renderer.js`)
- Map renderer → Style rules: configures source (evidence: `src/Renderer.js`)
- Map renderer → Label placement: places labels (evidence: `src/Renderer.js`)
- Map renderer → Drawing canvas: draws features (evidence: `src/Renderer.js`)
- Map renderer → Map utilities: projects coordinates (evidence: `src/Renderer.js`)
- Drawing canvas → Braille buffer: writes pixels (evidence: `src/Canvas.js`)
- Braille buffer → Runtime settings: reads display mode (evidence: `src/BrailleBuffer.js`)
- Map interaction → Terminal: writes frames (evidence: `src/Mapscii.js`)
- Tile source → Vector tile server: persists downloaded tiles
