docs: add six interactive archify architecture diagrams

[vins13pattar]

Summary

Adds docs/architecture/ — six self-contained, explorable HTML diagrams of the platform, generated with archify, alongside their typed JSON sources so they can be regenerated and reviewed as text.

Diagram	Type	What it answers
system.html	architecture	Which services exist, what they own, and how they talk
position-hot-path.html	sequence	What happens between a GPS frame and a marker moving on the map
tenant-isolation.html	workflow	How a credential becomes a tenant-scoped Postgres transaction
telemetry-lineage.html	dataflow	Where a fix is stored, what is derived from it, and when it ages out
device-session.html	lifecycle	The states a tracker connection moves through, including refusals
deployment.html	architecture	Where each service runs in production and what it depends on

The Mermaid diagrams in docs/ARCHITECTURE.md stay as the quick read; these are the detailed companions, and both docs/ARCHITECTURE.md and the root README.md now link to them. The data-lineage and device-session views have no counterpart in the existing docs.

Content was verified against the code rather than the existing prose: recordPosition(), the ingest admission and sink path, withTenant/withSystem, the jobs scheduler task table, retention plan windows, and the fly.*.toml machine configs. The system and deployment diagrams pin meta.repository at 674840f and cite 13 source paths between them, so a cited path that disappears fails regeneration instead of going quietly stale.

Reviewer notes

• The HTML is ~715 KB per file (~4.2 MB total) because each embeds the viewer runtime and fonts to stay standalone. If that is too much weight for the repo, the alternative is committing only src/ and generating the HTML in CI — happy to switch.
• Two refusal edges in the tenant-isolation workflow take wide detours around the intervening lane. route: "drop" and explicit vertical endpoint sides were both rejected by the layout compiler as infeasible, so those edges use its automatic routes.

Security and privacy

• No credentials, real IMEIs, customer locations, or production data are included. The diagrams contain only architectural descriptions and the synthetic-friendly facts already published in docs/ARCHITECTURE.md; no secrets, hostnames beyond what the repo already documents, or device identifiers.
• Authentication, tenant isolation, and input-validation impacts were considered. No behaviour changes — this is documentation only. The tenant-isolation diagram describes the existing RLS model (NOSUPERUSER NOBYPASSRLS app role, app.tenant_id set transaction-locally, the reviewed SYSTEM_DATABASE_URL paths) without altering it.

Verification

Docs-only change: the diff touches nothing outside docs/ and README.md, so the application test suite is unaffected. Node dependencies were not installed in the environment this was authored in, so the commands below were not run — flagging that rather than ticking boxes:

• pnpm typecheck — not run (no application code changed)
• pnpm test — not run (no application code changed)
• pnpm build — not run (no application code changed)
• Relevant database/RLS or protocol tests were run — not run (no application code changed)

What was verified instead, per diagram:

• archify deliver --quality showcase — 9/9 artifact checks, 0 errors, 0 warnings on all six
• Repository evidence verified against the pinned revision for system (9 references) and deployment (4 references)
• archify visual-check in headless Chromium — containment and ≥6px projected text at 1440×900, 1600×1000, 1920×1080 and 2048×1320, light and dark
• Rendered screenshots reviewed by eye, which caught two things the automated checks passed: the workflow legend was showing archify's default agent-domain labels ("Agent logic", "Policy"), and a node label overflowed its box. Both fixed.

🤖 Generated with Claude Code

https://claude.ai/code/session_016i4eitqukrs4RQwtvkTPU2

---

Generated by Claude Code

[vins13pattar]

dependency-audit is failing, and it isn't this PR's

Failing check: dependency-audit — pnpm audit --audit-level high exits 1 on two newly-published high advisories:

Advisory	Package	Vulnerable	Patched	Path
GHSA-c83g-rgw3-j3cx — unbounded memory growth, eventual OOM	browserslist	<=4.28.6	>=4.28.7	apps__web > autoprefixer > browserslist
GHSA-73wf-gq98-2v4g — crash / prototype write via untrusted browserslist-stats.json	browserslist	<=4.28.6	>=4.28.7	apps__web > autoprefixer > browserslist

Why it isn't this PR's: the diff touches only docs/ and README.md. It modifies no package.json and no pnpm-lock.yaml, so the lockfile this job audits is byte-identical to the one on main. pnpm audit reads the lockfile, so it produces the same result on both — this is a base-branch condition that surfaced here only because opening the PR ran the workflow today. main last ran security.yml successfully on 2026-08-31 (674840f), before these advisories were published; the workflow's scheduled runs on main have gone red the same way each time a new advisory lands.

I deliberately have not re-run the job. A re-run cannot help: the audit is deterministic against a fixed lockfile, so a second run would fail identically. Spending the re-run would prove nothing.

No fix PR exists to port, so rather than widening a docs PR with a dependency change, here is the proposed patch. It follows the convention already used in this repo for esbuild, hono, ip-address, nanoid, postcss, sharp and shell-quote:

   "pnpm": {
     "onlyBuiltDependencies": ["esbuild"],
     "overrides": {
+      "browserslist": "4.28.8",
       "esbuild": "0.28.1",
       "hono": "4.12.34",

…followed by pnpm install to regenerate pnpm-lock.yaml. Current resolution is browserslist@4.28.2, reached only through autoprefixer@10.5.0 in apps/web, so this is a patch-level bump within the same minor and should be low risk. 4.28.8 is the latest published version and satisfies the >=4.28.7 requirement in both advisories.

This belongs in its own PR so the dependency change is reviewable on its own terms, and because merging a security bump bundled into a documentation change is a poor audit trail. Happy to open that PR on request.

Every other check on this head is green: sast, secret-scan, sbom, mobile-dependency-audit, mobile-test (verify still running at the time of writing).

---

Generated by Claude Code