# liammccall/giatlas architecture

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

- Interactive diagram: https://gitdiagram.com/liammccall/giatlas
- Repository: https://github.com/liammccall/giatlas

## Overview

GiAtlas lets users submit natural-language spatial queries, turns them into constrained SQL, executes them against PostGIS, and displays returned GeoJSON on a Leaflet map. A separate save flow ingests Natural Earth data; the backend also exposes dataset and image-rendering routes. The README describes an LLM router, but no router source appears in the supplied tree, so it is shown only as an external service. Relationships are limited to those visible in excerpts or documented in the README.

Main entry points: [`webserver/src/python/main.py`](https://github.com/liammccall/giatlas/blob/main/webserver/src/python/main.py) (API routes), [`webserver/src/python/db/util.py`](https://github.com/liammccall/giatlas/blob/main/webserver/src/python/db/util.py) (Spatial query access), [`webserver/src/python/db/basicdb.py`](https://github.com/liammccall/giatlas/blob/main/webserver/src/python/db/basicdb.py) (Dataset access), [`client/src/App.tsx`](https://github.com/liammccall/giatlas/blob/main/client/src/App.tsx) (Query and map UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Map frontend"]
  node_app["Query and map UI<br/>[App.tsx]"]
  node_leaflet["Leaflet rendering<br/>[App.tsx]"]
end

subgraph group_api["Flask API"]
  node_flask["API routes<br/>[main.py]"]
  node_geojson["GeoJSON response<br/>[main.py]"]
  node_image["Image rendering<br/>[basicplotutil.py]"]
end

subgraph group_query["Query processing"]
  node_translate["SQL translation<br/>[mlinject.py]"]
  node_validate["SQL safety checks<br/>[mlinject.py]"]
end

subgraph group_storage["Spatial data"]
  node_dbutil["Spatial query access<br/>[util.py]"]
  node_database[("PostGIS")]
  node_basicdb["Dataset access<br/>[basicdb.py]"]
  node_indexing["Shape indexing<br/>[indexing.py]"]
  node_shapeindex["Index model<br/>[index.py]"]
end

node_user(("Explorer"))
node_llm["LLM router"]
node_naturalearth["Natural Earth"]
node_tiles["Map tiles"]

node_user -->|"enters query"| node_app
node_app -->|"posts query"| node_flask
node_flask -->|"requests SQL"| node_translate
node_translate -->|"requests SQL"| node_llm
node_translate -->|"checks output"| node_validate
node_validate -->|"runs query"| node_dbutil
node_dbutil -->|"queries"| node_database
node_flask -->|"loads fallback"| node_basicdb
node_flask -->|"serializes results"| node_geojson
node_basicdb -->|"reads datasets"| node_database
node_geojson -->|"returns GeoJSON"| node_app
node_app -->|"renders features"| node_leaflet
node_leaflet -->|"loads tiles"| node_tiles
node_flask -->|"ingests dataset"| node_basicdb
node_basicdb -->|"reads source data"| node_naturalearth
node_basicdb -->|"saves spatial data"| node_dbutil
node_dbutil -->|"writes data"| node_database
node_dbutil -->|"updates index"| node_indexing
node_indexing -->|"queries model"| node_shapeindex
node_indexing -->|"updates index"| node_database
node_flask -->|"renders image"| node_image

click node_app "https://github.com/liammccall/giatlas/blob/main/client/src/App.tsx"
click node_leaflet "https://github.com/liammccall/giatlas/blob/main/client/src/App.tsx"
click node_flask "https://github.com/liammccall/giatlas/blob/main/webserver/src/python/main.py"
click node_geojson "https://github.com/liammccall/giatlas/blob/main/webserver/src/python/main.py"
click node_image "https://github.com/liammccall/giatlas/blob/main/webserver/src/python/basicplotutil.py"
click node_translate "https://github.com/liammccall/giatlas/blob/main/webserver/src/python/mlinject.py"
click node_validate "https://github.com/liammccall/giatlas/blob/main/webserver/src/python/mlinject.py"
click node_dbutil "https://github.com/liammccall/giatlas/blob/main/webserver/src/python/db/util.py"
click node_basicdb "https://github.com/liammccall/giatlas/blob/main/webserver/src/python/db/basicdb.py"
click node_indexing "https://github.com/liammccall/giatlas/blob/main/webserver/src/python/db/stored_proc/indexing.py"
click node_shapeindex "https://github.com/liammccall/giatlas/blob/main/webserver/src/python/db/entities/index.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_app,node_leaflet toneBlue
class node_flask,node_geojson,node_image toneAmber
class node_translate,node_validate,node_llm toneMint
class node_dbutil,node_database,node_basicdb,node_indexing,node_shapeindex toneRose
class node_user,node_naturalearth,node_tiles toneIndigo
```

## Components

### Map frontend

- [Query and map UI](https://github.com/liammccall/giatlas/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Leaflet rendering](https://github.com/liammccall/giatlas/blob/main/client/src/App.tsx): `client/src/App.tsx`

### Flask API

- [API routes](https://github.com/liammccall/giatlas/blob/main/webserver/src/python/main.py): `webserver/src/python/main.py`
- [GeoJSON response](https://github.com/liammccall/giatlas/blob/main/webserver/src/python/main.py): `webserver/src/python/main.py`
- [Image rendering](https://github.com/liammccall/giatlas/blob/main/webserver/src/python/basicplotutil.py): `webserver/src/python/basicplotutil.py`

### Query processing

- [SQL translation](https://github.com/liammccall/giatlas/blob/main/webserver/src/python/mlinject.py): `webserver/src/python/mlinject.py`
- [SQL safety checks](https://github.com/liammccall/giatlas/blob/main/webserver/src/python/mlinject.py): `webserver/src/python/mlinject.py`

### Spatial data

- [Spatial query access](https://github.com/liammccall/giatlas/blob/main/webserver/src/python/db/util.py): `webserver/src/python/db/util.py`
- **PostGIS**
- [Dataset access](https://github.com/liammccall/giatlas/blob/main/webserver/src/python/db/basicdb.py): `webserver/src/python/db/basicdb.py`
- [Shape indexing](https://github.com/liammccall/giatlas/blob/main/webserver/src/python/db/stored_proc/indexing.py): `webserver/src/python/db/stored_proc/indexing.py`
- [Index model](https://github.com/liammccall/giatlas/blob/main/webserver/src/python/db/entities/index.py): `webserver/src/python/db/entities/index.py`

### Other components

- **Explorer**
- **LLM router**
- **Natural Earth**
- **Map tiles**

## Connections

- Explorer → Query and map UI: enters query (evidence: `client/src/App.tsx`)
- Query and map UI → API routes: posts query (evidence: `client/src/App.tsx`)
- API routes → SQL translation: requests SQL (evidence: `webserver/src/python/main.py`)
- SQL translation → LLM router: requests SQL (evidence: `webserver/src/python/mlinject.py`)
- SQL translation → SQL safety checks: checks output (evidence: `webserver/src/python/mlinject.py`)
- SQL safety checks → Spatial query access: runs query (evidence: `webserver/src/python/mlinject.py`)
- Spatial query access → PostGIS: queries (evidence: `webserver/src/python/db/util.py`)
- API routes → Dataset access: loads fallback (evidence: `webserver/src/python/main.py`)
- API routes → GeoJSON response: serializes results (evidence: `webserver/src/python/main.py`)
- Dataset access → PostGIS: reads datasets (evidence: `webserver/src/python/db/basicdb.py`)
- GeoJSON response → Query and map UI: returns GeoJSON (evidence: `README.md`)
- Query and map UI → Leaflet rendering: renders features (evidence: `client/src/App.tsx`)
- Leaflet rendering → Map tiles: loads tiles (evidence: `client/src/App.tsx`)
- API routes → Dataset access: ingests dataset (evidence: `webserver/src/python/main.py`)
- Dataset access → Natural Earth: reads source data (evidence: `webserver/src/python/db/basicdb.py`)
- Dataset access → Spatial query access: saves spatial data (evidence: `webserver/src/python/db/basicdb.py`)
- Spatial query access → PostGIS: writes data (evidence: `webserver/src/python/db/util.py`)
- Spatial query access → Shape indexing: updates index (evidence: `webserver/src/python/db/util.py`)
- Shape indexing → Index model: queries model (evidence: `webserver/src/python/db/stored_proc/indexing.py`)
- Shape indexing → PostGIS: updates index (evidence: `webserver/src/python/db/stored_proc/indexing.py`)
- API routes → Image rendering: renders image (evidence: `webserver/src/python/main.py`)
