# kraina-ai/quackosm architecture

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

- Interactive diagram: https://gitdiagram.com/kraina-ai/quackosm
- Repository: https://github.com/kraina-ai/quackosm

## Overview

QuackOSM is a Python library and optional CLI for turning OpenStreetMap PBF data into GeoParquet, DuckDB, or GeoDataFrames. The main workflow accepts a PBF or geometry/extract request, filters and parses OSM data, then writes or returns the converted result. The README also documents geometry- and tag-based filtering, automatic extract downloads, caching, and geocoding. The reader and public conversion APIs are sampled; some detailed processing and extract internals are not, so those relationships are shown only where documented.

Main entry points: [`quackosm/pbf_file_reader.py`](https://github.com/kraina-ai/quackosm/blob/main/quackosm/pbf_file_reader.py) (PBF reader), [`quackosm/functions.py`](https://github.com/kraina-ai/quackosm/blob/main/quackosm/functions.py) (Conversion API), [`quackosm/cli.py`](https://github.com/kraina-ai/quackosm/blob/main/quackosm/cli.py) (CLI commands), [`quackosm/geocode.py`](https://github.com/kraina-ai/quackosm/blob/main/quackosm/geocode.py) (Geocoding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_public_api["Conversion API<br/>[functions.py]"]
  node_cli["CLI commands<br/>[cli.py]"]
end

subgraph group_inputs["Input discovery"]
  node_geohash["Geohash parsing<br/>[_geohash_parser.py]"]
  node_geocode["Geocoding<br/>[geocode.py]"]
  node_extracts["OSM extracts<br/>[functions.py]"]
end

subgraph group_processing["OSM processing"]
  node_pbf_reader["PBF reader<br/>[pbf_file_reader.py]"]
  node_tag_filter["Tag filters"]
  node_way_config["Way polygon config"]
  node_multiprocessing["Parquet workers"]
  node_intersection["Geometry intersection<br/>[_intersection.py]"]
end

subgraph group_outputs["Output and support"]
  node_parquet_output["GeoParquet output<br/>[functions.py]"]
  node_geodataframe["GeoDataFrame output<br/>[functions.py]"]
  node_duckdb_output[("DuckDB output<br/>[functions.py]")]
  node_metadata["GeoParquet metadata"]
  node_progress["Progress reporting<br/>[_rich_progress.py]"]
  node_typing["Type validation<br/>[_typing.py]"]
  node_constants["Shared constants<br/>[_constants.py]"]
  node_exceptions["Errors and warnings<br/>[_exceptions.py]"]
  node_deprecate["Deprecation support<br/>[_deprecate.py]"]
end

node_user(("Python user"))
node_cli_user(("CLI user"))
node_external_osm{{"OSM extract services"}}
node_external_geocoder{{"Nominatim geocoder"}}
node_duckdb[("DuckDB Spatial")]

node_user -->|"calls"| node_public_api
node_cli_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_public_api
node_public_api -->|"uses reader"| node_pbf_reader
node_cli -->|"uses reader"| node_pbf_reader
node_public_api -->|"requests extracts"| node_extracts
node_extracts -.->|"downloads data"| node_external_osm
node_cli -->|"selects extracts"| node_extracts
node_cli -->|"resolves query"| node_geocode
node_geocode -.->|"geocodes query"| node_external_geocoder
node_cli -->|"parses index"| node_geohash
node_pbf_reader -->|"applies filters"| node_tag_filter
node_pbf_reader -->|"configures polygons"| node_way_config
node_pbf_reader -->|"clips geometry"| node_intersection
node_pbf_reader -->|"processes parquet"| node_multiprocessing
node_pbf_reader -->|"queries spatial data"| node_duckdb
node_public_api -->|"writes GeoParquet"| node_parquet_output
node_public_api -->|"returns frame"| node_geodataframe
node_public_api -->|"exports database"| node_duckdb_output
node_public_api -.->|"writes metadata"| node_metadata
node_pbf_reader -->|"reports progress"| node_progress
node_tag_filter -->|"validates types"| node_typing
node_way_config -->|"validates types"| node_typing
node_pbf_reader -->|"raises errors"| node_exceptions
node_pbf_reader -->|"uses defaults"| node_constants
node_pbf_reader -->|"marks deprecated args"| node_deprecate

click node_public_api "https://github.com/kraina-ai/quackosm/blob/main/quackosm/functions.py"
click node_cli "https://github.com/kraina-ai/quackosm/blob/main/quackosm/cli.py"
click node_pbf_reader "https://github.com/kraina-ai/quackosm/blob/main/quackosm/pbf_file_reader.py"
click node_tag_filter "https://github.com/kraina-ai/quackosm/blob/main/quackosm/_osm_tags_filters.py"
click node_way_config "https://github.com/kraina-ai/quackosm/blob/main/quackosm/_osm_way_polygon_features.py"
click node_multiprocessing "https://github.com/kraina-ai/quackosm/blob/main/quackosm/_parquet_multiprocessing.py"
click node_intersection "https://github.com/kraina-ai/quackosm/blob/main/quackosm/_intersection.py"
click node_geohash "https://github.com/kraina-ai/quackosm/blob/main/quackosm/_geohash_parser.py"
click node_geocode "https://github.com/kraina-ai/quackosm/blob/main/quackosm/geocode.py"
click node_extracts "https://github.com/kraina-ai/quackosm/blob/main/quackosm/functions.py"
click node_parquet_output "https://github.com/kraina-ai/quackosm/blob/main/quackosm/functions.py"
click node_geodataframe "https://github.com/kraina-ai/quackosm/blob/main/quackosm/functions.py"
click node_duckdb_output "https://github.com/kraina-ai/quackosm/blob/main/quackosm/functions.py"
click node_metadata "https://github.com/kraina-ai/quackosm/blob/main/quackosm/_geoparquet_metadata.py"
click node_progress "https://github.com/kraina-ai/quackosm/blob/main/quackosm/_rich_progress.py"
click node_typing "https://github.com/kraina-ai/quackosm/blob/main/quackosm/_typing.py"
click node_constants "https://github.com/kraina-ai/quackosm/blob/main/quackosm/_constants.py"
click node_exceptions "https://github.com/kraina-ai/quackosm/blob/main/quackosm/_exceptions.py"
click node_deprecate "https://github.com/kraina-ai/quackosm/blob/main/quackosm/_deprecate.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_public_api,node_cli,node_user,node_cli_user toneBlue
class node_geohash,node_geocode,node_extracts,node_duckdb toneAmber
class node_pbf_reader,node_tag_filter,node_way_config,node_multiprocessing,node_intersection toneMint
class node_parquet_output,node_geodataframe,node_duckdb_output,node_metadata,node_progress,node_typing,node_constants,node_exceptions,node_deprecate toneRose
class node_external_osm,node_external_geocoder toneIndigo
```

## Components

### User interfaces

- [Conversion API](https://github.com/kraina-ai/quackosm/blob/main/quackosm/functions.py): `quackosm/functions.py`
- [CLI commands](https://github.com/kraina-ai/quackosm/blob/main/quackosm/cli.py): `quackosm/cli.py`

### Input discovery

- [Geohash parsing](https://github.com/kraina-ai/quackosm/blob/main/quackosm/_geohash_parser.py): `quackosm/_geohash_parser.py`
- [Geocoding](https://github.com/kraina-ai/quackosm/blob/main/quackosm/geocode.py): `quackosm/geocode.py`
- [OSM extracts](https://github.com/kraina-ai/quackosm/blob/main/quackosm/functions.py): `quackosm/functions.py`

### OSM processing

- [PBF reader](https://github.com/kraina-ai/quackosm/blob/main/quackosm/pbf_file_reader.py): `quackosm/pbf_file_reader.py`
- [Tag filters](https://github.com/kraina-ai/quackosm/blob/main/quackosm/_osm_tags_filters.py): `quackosm/_osm_tags_filters.py`
- [Way polygon config](https://github.com/kraina-ai/quackosm/blob/main/quackosm/_osm_way_polygon_features.py): `quackosm/_osm_way_polygon_features.py`
- [Parquet workers](https://github.com/kraina-ai/quackosm/blob/main/quackosm/_parquet_multiprocessing.py): `quackosm/_parquet_multiprocessing.py`
- [Geometry intersection](https://github.com/kraina-ai/quackosm/blob/main/quackosm/_intersection.py): `quackosm/_intersection.py`

### Output and support

- [GeoParquet output](https://github.com/kraina-ai/quackosm/blob/main/quackosm/functions.py): `quackosm/functions.py`
- [GeoDataFrame output](https://github.com/kraina-ai/quackosm/blob/main/quackosm/functions.py): `quackosm/functions.py`
- [DuckDB output](https://github.com/kraina-ai/quackosm/blob/main/quackosm/functions.py): `quackosm/functions.py`
- [GeoParquet metadata](https://github.com/kraina-ai/quackosm/blob/main/quackosm/_geoparquet_metadata.py): `quackosm/_geoparquet_metadata.py`
- [Progress reporting](https://github.com/kraina-ai/quackosm/blob/main/quackosm/_rich_progress.py): `quackosm/_rich_progress.py`
- [Type validation](https://github.com/kraina-ai/quackosm/blob/main/quackosm/_typing.py): `quackosm/_typing.py`
- [Shared constants](https://github.com/kraina-ai/quackosm/blob/main/quackosm/_constants.py): `quackosm/_constants.py`
- [Errors and warnings](https://github.com/kraina-ai/quackosm/blob/main/quackosm/_exceptions.py): `quackosm/_exceptions.py`
- [Deprecation support](https://github.com/kraina-ai/quackosm/blob/main/quackosm/_deprecate.py): `quackosm/_deprecate.py`

### Other components

- **Python user**
- **CLI user**
- **OSM extract services**
- **Nominatim geocoder**
- **DuckDB Spatial**

## Connections

- Python user → Conversion API: calls
- CLI user → CLI commands: invokes
- CLI commands → Conversion API: dispatches (evidence: `quackosm/cli.py`)
- Conversion API → PBF reader: uses reader (evidence: `quackosm/functions.py`)
- CLI commands → PBF reader: uses reader (evidence: `quackosm/cli.py`)
- Conversion API → OSM extracts: requests extracts (evidence: `README.md`)
- OSM extracts → OSM extract services: downloads data (evidence: `README.md`)
- CLI commands → OSM extracts: selects extracts (evidence: `quackosm/cli.py`)
- CLI commands → Geocoding: resolves query (evidence: `quackosm/cli.py`)
- Geocoding → Nominatim geocoder: geocodes query (evidence: `README.md`)
- CLI commands → Geohash parsing: parses index (evidence: `quackosm/cli.py`)
- PBF reader → Tag filters: applies filters (evidence: `quackosm/pbf_file_reader.py`)
- PBF reader → Way polygon config: configures polygons (evidence: `quackosm/pbf_file_reader.py`)
- PBF reader → Geometry intersection: clips geometry (evidence: `quackosm/_intersection.py`)
- PBF reader → Parquet workers: processes parquet (evidence: `quackosm/pbf_file_reader.py`)
- PBF reader → DuckDB Spatial: queries spatial data (evidence: `quackosm/pbf_file_reader.py`)
- Conversion API → GeoParquet output: writes GeoParquet (evidence: `README.md`)
- Conversion API → GeoDataFrame output: returns frame (evidence: `README.md`)
- Conversion API → DuckDB output: exports database (evidence: `README.md`)
- Conversion API → GeoParquet metadata: writes metadata
- PBF reader → Progress reporting: reports progress (evidence: `quackosm/pbf_file_reader.py`)
- Tag filters → Type validation: validates types (evidence: `quackosm/_osm_tags_filters.py`)
- Way polygon config → Type validation: validates types (evidence: `quackosm/_osm_way_polygon_features.py`)
- PBF reader → Errors and warnings: raises errors (evidence: `quackosm/pbf_file_reader.py`)
- PBF reader → Shared constants: uses defaults (evidence: `quackosm/pbf_file_reader.py`)
- PBF reader → Deprecation support: marks deprecated args (evidence: `quackosm/pbf_file_reader.py`)