echo6-docs/vault/docs/software/navi.md

title	type	tags	aliases	related	updated
navi — Offline Navigation Platform	reference	recon		deployment central themes nominatim-v5-reimport cc-rules	2026-07-13

navi — Offline Navigation Platform

Overview

navi is an offline-capable navigation web app served from recon-vm (VM 1130, 192.168.1.130). It provides geocoding, routing, land classification, fleet admin, and DEM-backed elevation data — all from self-hosted geo backends. Frontend is a Vite SPA; backend is a suite of 8 Python microservices behind nginx.

• URL: https://navi.echo6.co (fronted by utility caddy + authentik)
• Host: recon-vm (data node, VM 1130)
• Repos: github.com/zvx-echo6/navi (canonical), Forge mirror matt/navi
• Layout: monorepo — backend/ (Python) + frontend/ (Vite)
• Deploy path: /home/zvx/projects/repos/navi-mono (branch main, in sync with origin)

Architecture

Internet → Caddy (utility CT 101) → Authentik → nginx :8440 (navi-mono frontend)
                                                   ├─ /api/* → navi-* backends :8421-:8428
                                                   ├─ /tiles/* → tile proxy
                                                   └─ /dem/* → dem-origin :8441 (range-cached)
                                                           └─ /mnt/nas/nav/planet-dem.pmtiles (658 GB)

nginx Vhosts

Port	Vhost	Role
:8440	navi.echo6.co	Public front door — SPA from /mnt/nav/frontend, API gateway (/api/* → backends), tile/DEM proxies; range-caches DEM requests from :8441
:8441	dem-origin (localhost only)	Serves 658 GB planet-dem.pmtiles from /mnt/nas/nav/; never exposed directly

Backend Services

All 8 are gunicorn processes, bound to 127.0.0.1, working directory navi-mono/backend, env files in /etc/navi-backend/*.env.

#	Service	Port	Status	Purpose
1	navi-traffic	:8421	DISABLED	Traffic — now proxied externally to central.echo6.mesh:8000
2	navi-config	:8422	Active	deployment profile API
3	navi-contacts	:8423	Active	Contacts + address book
4	navi-landclass	:8424	Active	PAD-US land classification (Postgres padus DB)
5	navi-places	:8425	Active	OSM place detail/enrichment (Postgres overture DB)
6	navi-geo	:8426	Active	Geocode + reverse geocode (Photon + DEM + timezone)
7	navi-admin	:8427	Active	Fleet admin-info aggregator (auth-gated)
8	navi-offroute	:8428	Active	Off-network router + MVUM (Valhalla + PostGIS)

Shared backend modules: shared/auth.py (Authentik header validation), shared/admin_info.py.

Geo Backends (co-resident on recon-vm)

Service	Version	Port	Runtime	Purpose	Consumed by
Valhalla	ghcr.io/valhalla/valhalla-scripted:latest	:8002	Docker (valhalla)	Routing engine	navi-offroute
Nominatim	5.3.2 (mediagis/nominatim:5.3.2)	:8010	Docker (nominatim-v5)	Geocoder — western-11 US states	navi-places
Photon	1.1.0 (jar)	:2322	Direct (Java process)	Reverse geocoder (komoot dump, embedded ES :9201)	navi-geo
PostgreSQL/PostGIS	—	:5432	System	DBs: padus (land classification), overture (OSM enrichment)	navi-landclass, navi-places

Nominatim coverage note: western-11 states only (AZ, CA, CO, ID, MT, NV, NM, OR, UT, WA, WY). Queries outside those states return country-level fallback only. Nominatim was upgraded from v4.5 → v5.3.2 on 2026-06-23 (fresh re-import; same coverage as before). Photon is independent of Nominatim — it runs from a komoot dump and was not changed.

Data

Path	Contents
/mnt/nav/	Addresses, timezones, OSM PBF, worldcover friction/barriers/trails, HPA, Photon data, frontend SPA build
/mnt/nas/nav/planet-dem.pmtiles	658 GB global DEM tile archive
/var/lib/navi-backend/	Writable runtime state: contacts.db, place_cache.db, wiki_index.db

NFS: pi-nas exports /mnt/nav and /mnt/nas to recon-vm.

Deployment

The repo ships its own deploy templates under backend/deploy/:

• deploy/systemd/ — all 8 unit files (match live)
• deploy/nginx/ — nginx vhost snippets (match live)
• deploy/env/ — env file templates (instances in /etc/navi-backend/)
• deploy/caddy/ — Caddy upstream fragment

Gotchas / Operational Notes

Three checkouts exist under ~/projects/repos/:

Checkout	Status
navi-mono/	Live — this is what runs
navi/	Stale — do not use
navi-backend/	Stale — do not delete without auditing (see below)

navi-backend/ cannot be deleted yet: several live env files (navi-config, navi-contacts, navi-places, navi-geo, navi-offroute) reference config, profile, and address-book files under /home/zvx/projects/repos/navi-backend/config/.... Document those paths before any cleanup.

Stale README: backend/README.md in the monorepo still refers to "extraction #1: navi-traffic" and predates the full monorepo consolidation. Treat backend/deploy/ as the authoritative source.