Skip to content

AGENTS.md

Latest commit

 

History

History
123 lines (87 loc) · 3.37 KB

AGENTS.md

File metadata and controls

123 lines (87 loc) · 3.37 KB

parqtiles AGENTS

Coding conventions

  • Go 1.22, standard library first, small dependencies.
  • Keep CLI parsing in cmd/parqtiles, core logic under internal/.
  • Logs must be JSON-friendly single-line entries to stdout.
  • Prefer explicit error handling with context; no panics for runtime errors.
  • Keep functions small and composable; avoid hidden global state.
  • In docs and UI copy, use Parqtiles for the product name; CLI commands remain parqtiles.

Performance notes

  • Stream data end-to-end; avoid materializing full datasets in memory.
  • Use DuckDB to read GeoParquet and export FlatGeobuf (no GeoJSON).
  • Keep steps idempotent and resumable for ECS batch execution.
  • Optimize for CPU-bound workloads during tiling (tippecanoe).

Plan format (declarative, Terraform-like)

parqtiles uses a declarative plan file as its primary interface. The plan defines what tiles should look like, not how to generate them.

Plan discovery

  • If --plan is provided, use it.
  • Otherwise, automatically load:
    • parqtiles.plan.yaml
    • parqtiles.plan.yml
  • If no plan file is found, fail with a clear error message.

Supported top-level sections

  • version
  • source
  • transform
  • tiling
  • output
  • runtime

The plan file must be explicit and deterministic. Hidden defaults should be avoided where possible.

source

Defines where input geospatial data comes from.

Supported fields:

  • format: input format (currently geoparquet)
  • uri: local path or glob (Docker-mounted path)
  • geometry_column: name of geometry column (default: geom)

transform

Defines logical transformations applied before tiling. This section must remain declarative.

Supported fields:

  • select: list of columns to read from input (optional)
  • where: SQL-like filter expression (optional)

Schema-driven property mapping (required pattern)

Property transformations must be schema-driven. Imperative concepts such as "rename" should be avoided.

Use schema to define the public tile schema explicitly.

Supported fields:

  • schema: output property definitions

Example:

schema: height: from: building_height kind: from: building_type

Rules:

  • Output properties are the keys of schema
  • from references input column names
  • Columns not referenced in schema are excluded
  • Geometry is implicit and does not need to be declared

tiling

Defines how tiles are generated.

Supported fields:

  • layer: vector tile layer name
  • minzoom: minimum zoom level
  • maxzoom: maximum zoom level
  • drop_densest_as_needed: boolean
  • extend_zooms_if_still_dropping: boolean

Tiling options should map to safe, well-understood vector tile behaviors. Advanced tool-specific flags should be exposed only via explicit escape hatches.

output

Defines the generated artifact.

Supported fields:

  • format: output format (currently pmtiles)
  • uri: local output path

runtime

Defines execution-related settings.

Supported fields:

  • tmpdir: directory for intermediate files

Runtime configuration must not affect logical output. Changing runtime settings must not change tile content.

Design principles

  • Plans are the source of truth.
  • Plans define intent, not procedures.
  • Plans should be stable, reviewable, and diff-friendly.
  • Output artifacts must be reproducible from the same plan and inputs.
  • The plan format is part of the public API and must evolve carefully.