---
type: guidelines
---
# Map minting guidelines

## 1. Artifacts are never committed
- Routing tiles and basemaps are large binaries rebuilt from upstream. This repo
  holds the scripts that produce them and a report of the procedure, nothing else.  
- Every build records the source PBF's date. An artifact whose provenance is
  unknown is an artifact to rebuild.

## 2. Build the admin database first, and from the *full* extract
- `valhalla_build_admins` is what determines driving side, and it is a separate
  step *before* the tile build.  
- **Always build it from `japan-latest.osm.pbf`, never a sub-region.** Driving side
  is a country-level property. A Shikoku extract yields only `admin_level=4`
  prefecture rows, no country record, and `drive_on_right=1` on every one —
  measured, not theorised.  
- The admin build and the tile build are separate invocations against the same
  config, so routing tiles may still come from a small regional extract while the
  admin database comes from the whole country.  
- **Verify, do not assume.** Every build checks that a country-level row exists and
  reports `drive_on_right=0` before the tiles are considered usable. This failure
  is silent otherwise: routing simply comes out mirrored.

## 3. Tiles ship as a directory, not a tar
- Once for RAM on an 8 GB board, once because `rsync` deltas a tree of changed
  files where a multi-gigabyte tar forces a full checksum at both ends.

## 4. To be added