Module Structure

Crate Layout

src/
├── main.rs                 — CLI entry point and argument parsing
├── config.rs               — Configuration types and validation
│
├── pipeline/
│   ├── mod.rs              — Pipeline orchestration (phases 1–4)
│   ├── reader.rs           — GeoParquet reader with column projection
│   ├── processor.rs        — Feature processing (project, clip, simplify)
│   ├── sorter.rs           — External merge sort coordinator
│   ├── encoder.rs          — MVT protobuf tile encoder
│   └── writer.rs           — PMTiles archive writer
│
├── geometry/
│   ├── mod.rs              — Geometry types and conversions
│   ├── projection.rs       — WGS84 → Web Mercator (EPSG:3857)
│   ├── clipping.rs         — Sutherland-Hodgman polygon/line clipping
│   └── simplify.rs         — Douglas-Peucker vertex simplification
│
├── layers/
│   ├── mod.rs              — Layer registry and trait definition
│   ├── earth.rs            — Earth polygons (land, ocean)
│   ├── water.rs            — Water bodies and waterways
│   ├── landuse.rs          — Land use and land cover areas
│   ├── buildings.rs        — Building footprints
│   ├── roads.rs            — Road network (all classes)
│   ├── transit.rs          — Transit lines and stations
│   ├── boundaries.rs       — Administrative boundaries
│   ├── places.rs           — Place labels (cities, towns, villages)
│   ├── pois.rs             — Points of interest
│   ├── natural.rs          — Natural features (parks, forests)
│   └── physical_line.rs    — Physical line features (coastlines, ridges)
│
├── tile/
│   ├── mod.rs              — TileID type (z/x/y) and Hilbert indexing
│   ├── mvt.rs              — Mapbox Vector Tile encoding (protobuf)
│   └── dedup.rs            — Content-hash tile deduplication
│
└── sort/
    ├── mod.rs              — External sort orchestration
    ├── chunk.rs            — LZ4-compressed sorted chunk I/O
    └── merge.rs            — K-way merge iterator

Module Responsibilities

`pipeline`

The top-level orchestrator. Connects the four phases (read → sort → encode → write) using crossbeam channels for backpressure-aware streaming. Each phase runs on its own thread pool.

Pure geometry operations with no I/O. The projection module handles coordinate transformation, clipping constrains geometries to tile boundaries, and simplification reduces vertex counts for lower zoom levels.

`layers`

Each layer module implements a Layer trait that defines:

Which Overture themes and types it reads
Which GeoParquet columns it needs (for column projection)
How to transform Overture properties into protomaps-compatible attributes
Min/max zoom visibility

The layer registry maps Overture data paths to layer implementations.

`tile`

Tile addressing and encoding. TileID represents a z/x/y coordinate with Hilbert curve index computation. The MVT encoder produces spec-compliant protobuf output. The deduplication module computes content hashes for identical tile detection.

`sort`

The external sort subsystem. Handles the creation, compression, and merging of sorted temporary files. Uses LZ4 frame compression for fast I/O on temporary chunks. The k-way merge uses a binary heap to efficiently combine sorted runs.

Key Dependencies

Crate	Purpose
`parquet`	Apache Parquet reader with column projection and predicate pushdown
`rayon`	Data parallelism for feature processing
`crossbeam`	Lock-free channels for inter-phase streaming
`prost`	Protobuf encoding for MVT tiles
`lz4_flex`	LZ4 compression for external sort chunks
`hilbert_2d`	Hilbert curve index computation
`clap`	CLI argument parsing
`env_logger`	Configurable logging via `RUST_LOG`