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

---
title: navi — Offline Navigation Platform
type: reference
tags: [recon]
related: ["[[recon]]", "[[services]]", "[[environment]]"]
updated: 2026-06-23
---
# 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.