# benjbaron/geonames architecture

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

- Interactive diagram: https://gitdiagram.com/benjbaron/geonames
- Repository: https://github.com/benjbaron/geonames

## Overview

This repository documents a GeoNames city-search product and includes a Jupyter data pipeline plus its generated CSV outputs. The main in-repository workflow filters GeoNames cities and postal-code records, matches them using loose coordinate precision, then assembles final feature attributes. The README also describes a browser search client hosted on another branch and an Algolia-backed suggestion service. Source excerpts were not provided, so relationships below rely only on README statements; the README excerpt does not establish how pipeline outputs reach Algolia.

Main entry points: [`GeoNames Cities Pipeline.ipynb`](https://github.com/benjbaron/geonames/blob/master/GeoNames%20Cities%20Pipeline.ipynb) (Filter postal codes), [`postcodes.csv`](https://github.com/benjbaron/geonames/blob/master/postcodes.csv) (Postal-code patterns), [`output`](https://github.com/benjbaron/geonames/tree/master/output) (Country CSV outputs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Data preparation"]
  node_geonames["GeoNames data"]
  node_postaldata["Postal-code data"]
  node_cityfilter["Filter city features"]
  node_postalfilter["Filter postal codes"]
  node_patterns["Postal-code patterns<br/>[postcodes.csv]"]
end

subgraph group_matching["City matching"]
  node_coordinatejoin["Coordinate matching"]
  node_aggregate["Aggregate matches"]
  node_attributejoin["Join feature attributes"]
  node_cityfiles["Country CSV outputs"]
end

subgraph group_search["Search service"]
  node_webclient["Search web client"]
  node_algolia["Algolia search"]
end

node_user(("Search user"))

node_geonames -->|"filters cities"| node_cityfilter
node_postaldata -->|"filters records"| node_postalfilter
node_patterns -->|"checks patterns"| node_postalfilter
node_cityfilter -->|"matches features"| node_coordinatejoin
node_postalfilter -->|"matches features"| node_coordinatejoin
node_coordinatejoin -->|"aggregates matches"| node_aggregate
node_aggregate -->|"joins attributes"| node_attributejoin
node_attributejoin -->|"produces files"| node_cityfiles
node_user -->|"enters search"| node_webclient
node_webclient -->|"requests suggestions"| node_algolia

click node_cityfilter "https://github.com/benjbaron/geonames/blob/master/GeoNames%20Cities%20Pipeline.ipynb"
click node_postalfilter "https://github.com/benjbaron/geonames/blob/master/GeoNames%20Cities%20Pipeline.ipynb"
click node_patterns "https://github.com/benjbaron/geonames/blob/master/postcodes.csv"
click node_coordinatejoin "https://github.com/benjbaron/geonames/blob/master/GeoNames%20Cities%20Pipeline.ipynb"
click node_aggregate "https://github.com/benjbaron/geonames/blob/master/GeoNames%20Cities%20Pipeline.ipynb"
click node_attributejoin "https://github.com/benjbaron/geonames/blob/master/GeoNames%20Cities%20Pipeline.ipynb"
click node_cityfiles "https://github.com/benjbaron/geonames/tree/master/output"

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_geonames,node_postaldata,node_cityfilter,node_postalfilter,node_patterns,node_user toneBlue
class node_coordinatejoin,node_aggregate,node_attributejoin,node_cityfiles toneAmber
class node_webclient,node_algolia toneMint
```

## Components

### Data preparation

- **GeoNames data**
- **Postal-code data**
- [Filter city features](https://github.com/benjbaron/geonames/blob/master/GeoNames%20Cities%20Pipeline.ipynb): `GeoNames Cities Pipeline.ipynb`
- [Filter postal codes](https://github.com/benjbaron/geonames/blob/master/GeoNames%20Cities%20Pipeline.ipynb): `GeoNames Cities Pipeline.ipynb`
- [Postal-code patterns](https://github.com/benjbaron/geonames/blob/master/postcodes.csv): `postcodes.csv`

### City matching

- [Coordinate matching](https://github.com/benjbaron/geonames/blob/master/GeoNames%20Cities%20Pipeline.ipynb): `GeoNames Cities Pipeline.ipynb`
- [Aggregate matches](https://github.com/benjbaron/geonames/blob/master/GeoNames%20Cities%20Pipeline.ipynb): `GeoNames Cities Pipeline.ipynb`
- [Join feature attributes](https://github.com/benjbaron/geonames/blob/master/GeoNames%20Cities%20Pipeline.ipynb): `GeoNames Cities Pipeline.ipynb`
- [Country CSV outputs](https://github.com/benjbaron/geonames/tree/master/output): `output`

### Search service

- **Search web client**
- **Algolia search**

### Other components

- **Search user**

## Connections

- GeoNames data → Filter city features: filters cities (evidence: `README.md`)
- Postal-code data → Filter postal codes: filters records (evidence: `README.md`)
- Postal-code patterns → Filter postal codes: checks patterns (evidence: `README.md`)
- Filter city features → Coordinate matching: matches features (evidence: `README.md`)
- Filter postal codes → Coordinate matching: matches features (evidence: `README.md`)
- Coordinate matching → Aggregate matches: aggregates matches (evidence: `README.md`)
- Aggregate matches → Join feature attributes: joins attributes (evidence: `README.md`)
- Join feature attributes → Country CSV outputs: produces files (evidence: `README.md`)
- Search user → Search web client: enters search (evidence: `README.md`)
- Search web client → Algolia search: requests suggestions (evidence: `README.md`)