# Module Structure

> Overview of the geolith codebase organization and module responsibilities.

## 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              — MVT encoding (protobuf via prost)
│   └── dedup.rs            — Content-hash tile deduplication
│
├── mlt.rs                  — MLT encoding (columnar via mlt-core, default format)
│
└── 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.

### `geometry`

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` |