# UNOCC Self-Service Mapping Platform — Live System Architecture (v2, 2026-06-10)

This document describes the architecture of the UNOCC Self-Service Mapping Platform as deployed and operating in production at **https://maps.shirob.com**. It supersedes the April 2026 v1 briefing, which described a planned system. The platform now serves three client channels — a web dashboard, a native Android app, and a native iOS app — backed by a single self-hosted VPS running the public API, the job queue, object storage, and a containerized QGIS cartographic render engine.

## 1. The Four Planes

The live system is organized into four planes: the Client plane (how users reach the service), the API plane (authentication, request intake, data proxying), the Render plane (the cartographic engine that builds the maps), and the Delivery plane (how finished products reach users).

## 2. Client Plane — Web, Android, iOS

### 2.1 Web Dashboard
The web dashboard at maps.shirob.com is a single-file HTML application served as a static asset. Users log in through a portal page (UNOCC, DPPA/DPO, EOSG cards) with username and password; the browser receives a JWT session token. The dashboard offers the full product suite: an interactive Leaflet map viewer, map product builders (Watchroom, ECDC, FactPack, Reference, DPPA), four geostatistical analysis pipelines (Kernel Density, Fishnet Spread, EHSA Hot-Spots, Fatality Clusters) with calendar date pickers and ACLED event-type and actor-type filter checkboxes, a Reports view of all builds, a Kanban production board, and email sharing of finished maps.

### 2.2 Orbis — Android App (LIVE)
Orbis is the native mobile app, built with Expo / React Native from a single codebase. The Android build is a standalone signed APK, currently distributed by direct sideload to user devices. It is live and verified on real hardware. The app provides: New Map request form covering all nine map products, native calendar date pickers for analysis timeframes, country autocomplete, ACLED filter chips, request status tracking with downloadable deliverables (PDF, PNG, PPTX), and email delivery to the requesting user. The production API endpoint and client credential are baked in at build time, so the app works from any network — office, home, or field.

### 2.3 Orbis — iOS App (TestFlight rollout in progress)
The iOS build shares 100% of the Orbis codebase, name, and icon. Distribution is via Apple TestFlight under a paid Apple Developer Program membership (enrolled June 2026): a signed build is uploaded to App Store Connect, and up to 10,000 external testers can install via an invite link — the planned channel for the ~30 initial iPhone users. TestFlight builds auto-update and expire after 90 days, requiring a quarterly re-upload.

### 2.4 Identity and Access
All three clients authenticate to the same API. The web dashboard uses per-user JWT logins (bcrypt-hashed users stored in Baserow). The mobile app uses a shared client credential plus a server-side email allowlist: only allowlisted UN email addresses (currently 10) can submit map requests or view request status. Every submission and build is recorded in an audit log table with source IP and parameter hash.

## 3. API Plane — Single VPS, Docker Stack

Everything public runs on one Hostinger KVM4 VPS (16 GB RAM) as Docker containers behind a Caddy reverse proxy that terminates TLS for maps.shirob.com.

### 3.1 FastAPI Public API (unocc-api)
The API container handles: user login and JWT issuance; map request submission and status (allowlist-enforced); the dashboard build-flow shims (POST /api/{product}/build) that translate the dashboard's job protocol into queue rows; email sharing of finished maps (PDF/PNG/PPTX attachments only, sent as "UNOCC GIS Self Service"); a whitelisted read-proxy to the cloud Supabase GIS database (specific RPCs and tables only — the browser never holds database credentials); and an ACLED OAuth proxy so the real ACLED token never leaves the server.

### 3.2 Baserow — Queue and Records
Baserow (self-hosted) is the system of record: the map_requests table is the render job queue (status: pending → claimed → rendering → done/error); separate tables hold the email allowlist, the user accounts, and the audit log.

### 3.3 MinIO — Object Storage
Finished map outputs (PDF, PNG, PPTX, GeoJSON, reports) are uploaded to a MinIO bucket. Clients download via time-limited presigned URLs served same-origin through Caddy, so no storage credentials are ever exposed.

## 4. Render Plane — Containerized QGIS Engine

A dedicated render-worker container (QGIS 4.0.2 headless on Linux) polls the Baserow queue every 10 seconds, claims pending requests, renders them in-process, uploads outputs to MinIO, and emails the requester. Concurrency is 1 — renders yield CPU to other workloads. The PyQGIS build scripts are bind-mounted from the host, so cartographic fixes deploy by file sync with no container rebuild.

### 4.1 Product Catalog (nine products)
- **Watchroom** — situational-awareness country basemap (PNG)
- **ECDC Basemap** — chrome-free slide basemap, emitted into the ECDC PowerPoint template with live World Bank statistics (PNG + PPTX)
- **FactPack** — country fact-pack cover map with capital-city margin guarantee, emitted into the FactPack PowerPoint template (PNG + PPTX)
- **Reference Map** — 30×24-inch wall-print PDF with terrain and vegetation options
- **DPPA Map** — clean reference basemap with selectable infrastructure/humanitarian layers (PDF)
- **Kernel Density (KDE)** — ACLED event-density heat map
- **Fishnet Spread** — baseline-vs-current percent-change conflict analysis with three briefing panels; supports precise analyst-chosen date ranges (split at the midpoint into the SOP's two sub-windows) or calendar-year pairs
- **EHSA Hot-Spots** — emerging hot spot / conflict trend classification (30 km hex cells)
- **Fatality Clusters** — DBSCAN fatality clustering overlay

### 4.2 Cartographic Data Sources
UN Geodata 1M GeoPackage (authoritative boundaries; BNDA/BNDL), ACLED conflict events (OAuth API), OpenStreetMap settlement extracts with density-protocol thinning, Natural Earth (rivers, roads, lakes, marine polygons), ESA WorldCover vegetation, Natural Earth Gray Earth shaded relief, OurAirports, and the World Bank Indicators API for ECDC statistics. Neighbouring-country labels follow UN cartographic data with common-name shortening (e.g. Laos, North Korea, DR Congo) and guaranteed label placement so no visible neighbour goes unlabeled.

## 5. Delivery Plane

Finished products reach users three ways: in-app/in-browser download via presigned MinIO URLs; the Share/Email function (recipient-validated, ≤20 recipients, attachments compressed to mail-safe size, sender "UNOCC GIS Self Service"); and automatic delivery email to the requesting address when a mobile-submitted job completes.

## 6. Security Posture

TLS everywhere via Caddy; JWT (HS256) sessions with bcrypt-hashed credentials; server-side email allowlist gating submissions; whitelisted-only database RPC/table proxy (anon key server-side, service-role keys never leave the server); ACLED credentials server-side only; client-supplied file paths validated against allowed roots before any email attachment; audit logging of logins, submissions, builds, and shares; secrets held in chmod-600 env files outside the image; and the mobile APK — which embeds a client credential — is distributed only by direct/LAN transfer, never from a public URL.

## 7. Cost Footprint

The entire public platform — API, queue, storage, render engine, and TLS edge — runs on a single ~$30/month KVM4 VPS plus a $99/year Apple Developer membership for iOS distribution. There are no managed-PaaS dependencies; scaling is by adding VPS nodes per the phased rollout plan.

## 8. What Changed Since v1 (April 2026)

The v1 briefing described a planned system centred on a local Mac dev server and a future VPS. As of June 2026: the public stack (Caddy + FastAPI + Baserow + MinIO + QGIS render worker) is live on the VPS; per-user JWT auth and the email allowlist are enforced; all nine products render in the cloud worker including the PowerPoint deck emission; the Android app (Orbis) is live on real devices via sideload; iOS distribution via TestFlight is in active rollout; and the Mac now serves only as the private development and personal-production environment.