# cristan/improved-un-locodes architecture

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

- Interactive diagram: https://gitdiagram.com/cristan/improved-un-locodes
- Repository: https://github.com/cristan/improved-un-locodes

## Overview

This repository is a curated UN/LOCODE data product, not a runtime service. Its central result is a location list with substantially improved coordinate coverage and accuracy; related outputs add place hierarchy and aliases. The README documents combining the base UN/LOCODE list with Nominatim and Wikidata, checking against alternative sources, and manual correction. The tree shows the Nominatim data directory, but not the other source files or the implementation of those enrichment steps, so those links reflect documented provenance rather than inspected code.

Main entry points: [`data/code-list-improved.csv`](https://github.com/cristan/improved-un-locodes/blob/main/data/code-list-improved.csv) (Improved locations), [`data/nominatim`](https://github.com/cristan/improved-un-locodes/tree/main/data/nominatim) (Nominatim records), [`data/aliases-improved.csv`](https://github.com/cristan/improved-un-locodes/blob/main/data/aliases-improved.csv) (Improved aliases)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sources["Data sources"]
  node_unlocode["Base UN/LOCODE"]
  node_nominatim["Nominatim records"]
  node_wikidata["Wikidata"]
  node_alternatives["Alternative sources"]
end

subgraph group_enrichment["Location enrichment"]
  node_manual["Manual review"]
  node_coord["Coordinate enrichment"]
end

subgraph group_outputs["Dataset outputs"]
  node_improved["Improved locations"]
  node_parents["Location hierarchy"]
  node_aliases["Improved aliases"]
end

node_consumer(("Dataset user"))

node_unlocode -->|"enriches"| node_coord
node_nominatim -->|"supplies locations"| node_coord
node_wikidata -->|"supplies data"| node_coord
node_coord -->|"checked against"| node_alternatives
node_alternatives -->|"informs review"| node_manual
node_manual -->|"corrects locations"| node_improved
node_coord -->|"improves coordinates"| node_improved
node_consumer -->|"uses"| node_improved
node_consumer -->|"uses"| node_parents
node_consumer -->|"uses"| node_aliases

click node_nominatim "https://github.com/cristan/improved-un-locodes/tree/main/data/nominatim"
click node_improved "https://github.com/cristan/improved-un-locodes/blob/main/data/code-list-improved.csv"
click node_aliases "https://github.com/cristan/improved-un-locodes/blob/main/data/aliases-improved.csv"

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_unlocode,node_nominatim,node_wikidata,node_alternatives,node_consumer toneBlue
class node_manual,node_coord toneAmber
class node_improved,node_parents,node_aliases toneMint
```

## Components

### Data sources

- **Base UN/LOCODE**
- [Nominatim records](https://github.com/cristan/improved-un-locodes/tree/main/data/nominatim): `data/nominatim`
- **Wikidata**
- **Alternative sources**

### Location enrichment

- **Manual review**
- **Coordinate enrichment**

### Dataset outputs

- [Improved locations](https://github.com/cristan/improved-un-locodes/blob/main/data/code-list-improved.csv): `data/code-list-improved.csv`
- **Location hierarchy**
- [Improved aliases](https://github.com/cristan/improved-un-locodes/blob/main/data/aliases-improved.csv): `data/aliases-improved.csv`

### Other components

- **Dataset user**

## Connections

- Base UN/LOCODE → Coordinate enrichment: enriches
- Nominatim records → Coordinate enrichment: supplies locations
- Wikidata → Coordinate enrichment: supplies data
- Coordinate enrichment → Alternative sources: checked against
- Alternative sources → Manual review: informs review
- Manual review → Improved locations: corrects locations
- Coordinate enrichment → Improved locations: improves coordinates
- Dataset user → Improved locations: uses
- Dataset user → Location hierarchy: uses
- Dataset user → Improved aliases: uses