auto: docs sync 2026-06-19T00:00:09+00:00

Files changed: engine/lint-report.md vault/.obsidian/graph.json vault/.obsidian/workspace.json vault/docs/hardware/environment.md vault/docs/services/services.md vault/docs/software/central.md vault/docs/software/navi.md vault/docs/software/recon.md
2026-06-19 00:00:09 +00:00 · 2026-06-19 00:00:09 +00:00 · 75df23b89e
commit 75df23b89e
parent eb7eade7fa
8 changed files with 280 additions and 38 deletions
--- a/vault/docs/software/navi.md
+++ b/vault/docs/software/navi.md
@ -0,0 +1,94 @@
+---
+title: navi — Offline Navigation Platform
+type: reference
+tags: [recon]
+related: ["[[recon]]", "[[services]]", "[[environment]]"]
+updated: 2026-06-18
+---
+# 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 | Port | Runtime | Purpose |
+|---------|------|---------|---------|
+| Valhalla | :8002 | Docker | Routing engine |
+| Nominatim | :8010 | Docker | Geocoder |
+| Photon | :2322 | Direct | Geocoder (embedded Elasticsearch :9201) |
+| PostgreSQL/PostGIS | :5432 | System | DBs: `padus` (land classification), `overture` (OSM enrichment) |
+
+## 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.