# a-shygun/terrascope architecture

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

- Interactive diagram: https://gitdiagram.com/a-shygun/terrascope
- Repository: https://github.com/a-shygun/terrascope

## Overview

Terrascope is a curses-based interactive world map. The user launches it, chooses a tab, navigates and inspects a rendered map, and can enable live layers. Its stages are CLI/configuration, map-data setup, world/frame construction, terminal rendering and input handling, with basemap, time, weather, and aircraft capabilities. The graph preserves these documented branches; some implementation paths are unsampled, so their internal links are omitted. Relationships shown use README statements or source-index references, not inferred sibling pipelines.

Main entry points: [`src/terrascope/layers/weather/layer.py`](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/layer.py) (Weather layer), [`src/terrascope/core/world.py`](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/world.py) (World map state), [`src/terrascope/core/mapdata.py`](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/mapdata.py) (Map data loading), [`src/terrascope/core/main.py`](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/main.py) (App startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_cli["CLI options<br/>[cli.py]"]
  node_startup["App startup<br/>[main.py]"]
  node_app["Interactive runtime"]
end

subgraph group_map["Map and terminal"]
  node_world["World map state<br/>[world.py]"]
  node_view["Projection and Braille<br/>[view.py]"]
  node_ui["Terminal map UI<br/>[map.py]"]
  node_layout["Panels and layout<br/>[layout.py]"]
  node_colors["Terminal colors<br/>[colors.py]"]
end

subgraph group_layers["Map layers"]
  node_registry["Layer registry<br/>[registry.py]"]
  node_layerbase["Layer framework<br/>[layer.py]"]
  node_basemap["Base world layer<br/>[layer.py]"]
  node_daynight["Day/night layer<br/>[layer.py]"]
  node_astronomy["Astronomy calculations<br/>[astronomy.py]"]
  node_weather["Weather layer<br/>[layer.py]"]
  node_cityweather["City weather<br/>[city_weather.py]"]
  node_forecast["Forecast panel<br/>[forecast.py]"]
  node_earthquakes["Earthquakes<br/>[earthquakes.py]"]
  node_radar["Radar overlay<br/>[radar.py]"]
  node_flights["Aircraft layer<br/>[layer.py]"]
  node_flightapi["Aircraft feed<br/>[api.py]"]
  node_flightformat["Aircraft formatting<br/>[formatting.py]"]
end

subgraph group_state["Settings and data"]
  node_config["Configuration<br/>[config.py]"]
  node_mapdata["Map data loading<br/>[mapdata.py]"]
  node_cache[("User cache<br/>[config.py]")]
  node_weatherconfig["Weather settings<br/>[config.py]"]
  node_flightsettings["Flight settings<br/>[settings.py]"]
end

node_user(("Terminal user"))
node_external(("External data services"))

node_user -->|"launches"| node_cli
node_cli -->|"overrides"| node_config
node_cli -->|"starts"| node_startup
node_startup -->|"runs"| node_app
node_startup -->|"loads"| node_mapdata
node_startup -->|"loads frames"| node_radar
node_config -->|"locates"| node_cache
node_mapdata -->|"stores downloads"| node_cache
node_app -->|"updates"| node_world
node_app -->|"renders"| node_ui
node_world -->|"renders layers"| node_layerbase
node_world -->|"uses projection"| node_view
node_ui -->|"displays frame"| node_view
node_ui -->|"uses colors"| node_colors
node_ui -->|"uses layout"| node_layout
node_registry -->|"registers layers"| node_layerbase
node_world -->|"uses geometry"| node_mapdata
node_basemap -->|"uses map data"| node_mapdata
node_daynight -->|"uses calculations"| node_astronomy
node_weather -->|"uses readings"| node_cityweather
node_weather -->|"uses forecast"| node_forecast
node_weather -->|"uses feed"| node_earthquakes
node_weather -->|"uses radar"| node_radar
node_weather -->|"reads settings"| node_weatherconfig
node_flights -->|"fetches aircraft"| node_flightapi
node_flights -->|"formats data"| node_flightformat
node_flights -->|"reads settings"| node_flightsettings
node_mapdata -->|"downloads Natural Earth"| node_external
node_cityweather -.->|"requests weather"| node_external
node_radar -.->|"fetches radar"| node_external
node_flightapi -.->|"fetches OpenSky"| node_external
node_user -->|"navigates map"| node_world

click node_cli "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/cli.py"
click node_startup "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/main.py"
click node_app "https://github.com/a-shygun/terrascope/tree/main/src/terrascope/core/app"
click node_config "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/config.py"
click node_registry "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/registry.py"
click node_mapdata "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/mapdata.py"
click node_cache "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/config.py"
click node_world "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/world.py"
click node_view "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/view.py"
click node_layerbase "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/layer.py"
click node_ui "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/ui/map.py"
click node_layout "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/ui/layout.py"
click node_colors "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/ui/colors.py"
click node_basemap "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/basemap/layer.py"
click node_daynight "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/daynight/layer.py"
click node_astronomy "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/daynight/astronomy.py"
click node_weather "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/layer.py"
click node_cityweather "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/city_weather.py"
click node_forecast "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/forecast.py"
click node_earthquakes "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/earthquakes.py"
click node_radar "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/radar.py"
click node_weatherconfig "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/config.py"
click node_flights "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/flights/layer.py"
click node_flightapi "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/flights/api.py"
click node_flightformat "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/flights/formatting.py"
click node_flightsettings "https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/flights/settings.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_cli,node_startup,node_app,node_user toneBlue
class node_world,node_view,node_ui,node_layout,node_colors toneAmber
class node_registry,node_layerbase,node_basemap,node_daynight,node_astronomy,node_weather,node_cityweather,node_forecast,node_earthquakes,node_radar,node_flights,node_flightapi,node_flightformat toneMint
class node_config,node_mapdata,node_cache,node_weatherconfig,node_flightsettings toneRose
class node_external toneIndigo
```

## Components

### Application entry

- [CLI options](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/cli.py): `src/terrascope/core/cli.py`
- [App startup](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/main.py): `src/terrascope/core/main.py`
- [Interactive runtime](https://github.com/a-shygun/terrascope/tree/main/src/terrascope/core/app): `src/terrascope/core/app`

### Map and terminal

- [World map state](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/world.py): `src/terrascope/core/world.py`
- [Projection and Braille](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/view.py): `src/terrascope/core/view.py`
- [Terminal map UI](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/ui/map.py): `src/terrascope/core/ui/map.py`
- [Panels and layout](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/ui/layout.py): `src/terrascope/core/ui/layout.py`
- [Terminal colors](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/ui/colors.py): `src/terrascope/core/ui/colors.py`

### Map layers

- [Layer registry](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/registry.py): `src/terrascope/core/registry.py`
- [Layer framework](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/layer.py): `src/terrascope/core/layer.py`
- [Base world layer](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/basemap/layer.py): `src/terrascope/layers/basemap/layer.py`
- [Day/night layer](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/daynight/layer.py): `src/terrascope/layers/daynight/layer.py`
- [Astronomy calculations](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/daynight/astronomy.py): `src/terrascope/layers/daynight/astronomy.py`
- [Weather layer](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/layer.py): `src/terrascope/layers/weather/layer.py`
- [City weather](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/city_weather.py): `src/terrascope/layers/weather/city_weather.py`
- [Forecast panel](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/forecast.py): `src/terrascope/layers/weather/forecast.py`
- [Earthquakes](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/earthquakes.py): `src/terrascope/layers/weather/earthquakes.py`
- [Radar overlay](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/radar.py): `src/terrascope/layers/weather/radar.py`
- [Aircraft layer](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/flights/layer.py): `src/terrascope/layers/flights/layer.py`
- [Aircraft feed](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/flights/api.py): `src/terrascope/layers/flights/api.py`
- [Aircraft formatting](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/flights/formatting.py): `src/terrascope/layers/flights/formatting.py`

### Settings and data

- [Configuration](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/config.py): `src/terrascope/core/config.py`
- [Map data loading](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/mapdata.py): `src/terrascope/core/mapdata.py`
- [User cache](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/core/config.py): `src/terrascope/core/config.py`
- [Weather settings](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/weather/config.py): `src/terrascope/layers/weather/config.py`
- [Flight settings](https://github.com/a-shygun/terrascope/blob/main/src/terrascope/layers/flights/settings.py): `src/terrascope/layers/flights/settings.py`

### Other components

- **Terminal user**
- **External data services**

## Connections

- Terminal user → CLI options: launches
- CLI options → Configuration: overrides (evidence: `src/terrascope/core/cli.py`)
- CLI options → App startup: starts (evidence: `src/terrascope/core/cli.py`)
- App startup → Interactive runtime: runs (evidence: `src/terrascope/core/main.py`)
- App startup → Map data loading: loads (evidence: `src/terrascope/core/main.py`)
- App startup → Radar overlay: loads frames (evidence: `src/terrascope/core/main.py`)
- Configuration → User cache: locates (evidence: `src/terrascope/core/config.py`)
- Map data loading → User cache: stores downloads (evidence: `src/terrascope/core/mapdata.py`)
- Interactive runtime → World map state: updates (evidence: `src/terrascope/core/app/shared.py`)
- Interactive runtime → Terminal map UI: renders (evidence: `src/terrascope/core/app/shared.py`)
- World map state → Layer framework: renders layers (evidence: `src/terrascope/core/world.py`)
- World map state → Projection and Braille: uses projection (evidence: `src/terrascope/core/world.py`)
- Terminal map UI → Projection and Braille: displays frame (evidence: `src/terrascope/core/ui/map.py`)
- Terminal map UI → Terminal colors: uses colors (evidence: `src/terrascope/core/ui/map.py`)
- Terminal map UI → Panels and layout: uses layout (evidence: `src/terrascope/core/ui/map.py`)
- Layer registry → Layer framework: registers layers (evidence: `src/terrascope/core/registry.py`)
- World map state → Map data loading: uses geometry (evidence: `src/terrascope/core/world.py`)
- Base world layer → Map data loading: uses map data (evidence: `src/terrascope/layers/basemap/layer.py`)
- Day/night layer → Astronomy calculations: uses calculations (evidence: `src/terrascope/layers/daynight/layer.py`)
- Weather layer → City weather: uses readings (evidence: `src/terrascope/layers/weather/layer.py`)
- Weather layer → Forecast panel: uses forecast (evidence: `src/terrascope/layers/weather/layer.py`)
- Weather layer → Earthquakes: uses feed (evidence: `src/terrascope/layers/weather/layer.py`)
- Weather layer → Radar overlay: uses radar (evidence: `src/terrascope/layers/weather/layer.py`)
- Weather layer → Weather settings: reads settings (evidence: `src/terrascope/layers/weather/layer.py`)
- Aircraft layer → Aircraft feed: fetches aircraft (evidence: `src/terrascope/layers/flights/layer.py`)
- Aircraft layer → Aircraft formatting: formats data (evidence: `src/terrascope/layers/flights/layer.py`)
- Aircraft layer → Flight settings: reads settings (evidence: `src/terrascope/layers/flights/layer.py`)
- Map data loading → External data services: downloads Natural Earth
- City weather → External data services: requests weather
- Radar overlay → External data services: fetches radar (evidence: `src/terrascope/layers/weather/radar.py`)
- Aircraft feed → External data services: fetches OpenSky
- Terminal user → World map state: navigates map