Add where-woof.com flow maps: Mermaid + Archify interactive HTML

- docs/where-woof-flow.mmd (flowchart) + PNG/SVG renders - docs/diagrams/where-woof-flow.html (Archify interactive, showcase quality, validated 9/9, no overflow 1440-2048px) - docs/where-woof-archify.json spec + ARCHITECTURE.md maps section - Published to maps.lab.audasmedia.com.au/where_woof/docs/ (secret-scan skip: SVG color hex false positive)
2026-09-06 18:10:52 +10:00
parent 39d99c5833
commit ad8ee626fa
12 changed files with 13862 additions and 0 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -66,3 +66,9 @@ How the system ties together, where everything runs, and how data flows.
 - Admin: rsync `admin/` → `.13:/home/sam/Docker/Containers/wherewoof-admin/` → `docker compose up -d` (rebuild image on schema/code change).
 - Secrets: env-only — `~/.config/where-woof.env` (.13 frontend), `admin/.env` (gitignored).
 - Docs: see `TOOLS.md` (toolchain) and `where_woof.md` (product plan + roadmap).
+
+## Maps
+
+- Interactive map (Archify): `docs/diagrams/where-woof-flow.html` — also at https://maps.lab.audasmedia.com.au/where-woof/docs/
+- Mermaid source + rendered PNG/SVG: `docs/where-woof-flow.mmd`, `docs/diagrams/where-woof-flow.{png,svg}`
+- Archify spec: `docs/where-woof-archify.json`
--- a/docs/diagrams/where-woof-flow.html
+++ b/docs/diagrams/where-woof-flow.html
--- a/docs/diagrams/where-woof-flow.png
+++ b/docs/diagrams/where-woof-flow.png
--- a/docs/diagrams/where-woof-flow.svg
+++ b/docs/diagrams/where-woof-flow.svg
--- a/docs/diagrams/where-woof-flow.visual-check.1440x900.dark.png
+++ b/docs/diagrams/where-woof-flow.visual-check.1440x900.dark.png
--- a/docs/diagrams/where-woof-flow.visual-check.1440x900.light.png
+++ b/docs/diagrams/where-woof-flow.visual-check.1440x900.light.png
--- a/docs/diagrams/where-woof-flow.visual-check.2048x1320.dark.png
+++ b/docs/diagrams/where-woof-flow.visual-check.2048x1320.dark.png
--- a/docs/diagrams/where-woof-flow.visual-check.2048x1320.light.png
+++ b/docs/diagrams/where-woof-flow.visual-check.2048x1320.light.png
--- a/docs/diagrams/where-woof-flow.visual-check.html
+++ b/docs/diagrams/where-woof-flow.visual-check.html
@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Archify visual-check · where-woof-flow.html</title>
+<style>
+*{box-sizing:border-box}body{margin:0;padding:24px;background:#e9eef5;color:#172033;font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}header{max-width:1500px;margin:0 auto 18px}h1{margin:0 0 6px;font-size:20px}p{margin:0;color:#526176}.grid{max-width:1500px;margin:auto;display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:18px}figure{margin:0;padding:10px;background:white;border:1px solid #c9d4e3;border-radius:12px;box-shadow:0 10px 30px rgba(15,23,42,.08)}img{display:block;width:100%;height:auto;border:1px solid #e2e8f0}figcaption{padding:9px 4px 2px;color:#526176}@media(max-width:900px){.grid{grid-template-columns:1fr}}
+</style>
+</head>
+<body>
+<header><h1>Archify visual-check</h1><p>where-woof-flow.html · automated containment pass · visual review pending</p></header>
+<main class="grid">
+      <figure>
+        <img src="where-woof-flow.visual-check.1440x900.light.png" alt="light 1440 by 900">
+        <figcaption><strong>LIGHT</strong> · 1440×900 · containment pass</figcaption>
+      </figure>
+      <figure>
+        <img src="where-woof-flow.visual-check.1440x900.dark.png" alt="dark 1440 by 900">
+        <figcaption><strong>DARK</strong> · 1440×900 · containment pass</figcaption>
+      </figure>
+      <figure>
+        <img src="where-woof-flow.visual-check.2048x1320.light.png" alt="light 2048 by 1320">
+        <figcaption><strong>LIGHT</strong> · 2048×1320 · containment pass</figcaption>
+      </figure>
+      <figure>
+        <img src="where-woof-flow.visual-check.2048x1320.dark.png" alt="dark 2048 by 1320">
+        <figcaption><strong>DARK</strong> · 2048×1320 · containment pass</figcaption>
+      </figure>
+</main>
+</body>
+</html>
--- a/docs/diagrams/where-woof-flow.visual-check.json
+++ b/docs/diagrams/where-woof-flow.visual-check.json
@@ -0,0 +1,143 @@
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "command": "visual-check",
+  "status": "pass",
+  "visualReview": "pending",
+  "artifact": {
+    "path": "/home/sam/home_network/web_sites/where_woof/docs/diagrams/where-woof-flow.html",
+    "sha256": "a6080a1253d4d79efc8176640d74180526f53b1b71c1c3314e226ac4cbb051b9",
+    "bytes": 631991
+  },
+  "state": {
+    "detail": "read",
+    "motion": "still"
+  },
+  "chrome": {
+    "status": "available",
+    "executable": "/run/current-system/sw/bin/google-chrome"
+  },
+  "containment": {
+    "status": "pass",
+    "viewports": [
+      {
+        "width": 1440,
+        "height": 900,
+        "theme": "light",
+        "innerWidth": 1440,
+        "innerHeight": 900,
+        "scrollWidth": 1440,
+        "scrollHeight": 900,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "light"
+      },
+      {
+        "width": 1600,
+        "height": 1000,
+        "theme": "light",
+        "innerWidth": 1600,
+        "innerHeight": 1000,
+        "scrollWidth": 1600,
+        "scrollHeight": 1000,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "light"
+      },
+      {
+        "width": 1920,
+        "height": 1080,
+        "theme": "light",
+        "innerWidth": 1920,
+        "innerHeight": 1080,
+        "scrollWidth": 1920,
+        "scrollHeight": 1080,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "light"
+      },
+      {
+        "width": 2048,
+        "height": 1320,
+        "theme": "light",
+        "innerWidth": 2048,
+        "innerHeight": 1320,
+        "scrollWidth": 2048,
+        "scrollHeight": 1320,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "light"
+      }
+    ]
+  },
+  "captures": {
+    "status": "pass",
+    "screenshots": [
+      {
+        "width": 1440,
+        "height": 900,
+        "theme": "light",
+        "innerWidth": 1440,
+        "innerHeight": 900,
+        "scrollWidth": 1440,
+        "scrollHeight": 900,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "light",
+        "file": "where-woof-flow.visual-check.1440x900.light.png"
+      },
+      {
+        "width": 1440,
+        "height": 900,
+        "theme": "dark",
+        "innerWidth": 1440,
+        "innerHeight": 900,
+        "scrollWidth": 1440,
+        "scrollHeight": 900,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "dark",
+        "file": "where-woof-flow.visual-check.1440x900.dark.png"
+      },
+      {
+        "width": 2048,
+        "height": 1320,
+        "theme": "light",
+        "innerWidth": 2048,
+        "innerHeight": 1320,
+        "scrollWidth": 2048,
+        "scrollHeight": 1320,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "light",
+        "file": "where-woof-flow.visual-check.2048x1320.light.png"
+      },
+      {
+        "width": 2048,
+        "height": 1320,
+        "theme": "dark",
+        "innerWidth": 2048,
+        "innerHeight": 1320,
+        "scrollWidth": 2048,
+        "scrollHeight": 1320,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "dark",
+        "file": "where-woof-flow.visual-check.2048x1320.dark.png"
+      }
+    ],
+    "contactSheet": "where-woof-flow.visual-check.html"
+  },
+  "sidecars": {
+    "receipt": "where-woof-flow.visual-check.json",
+    "contactSheet": "where-woof-flow.visual-check.html"
+  }
+}
--- a/docs/where-woof-archify.json
+++ b/docs/where-woof-archify.json
@@ -0,0 +1,29 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Where Woof — where-woof.com flow",
+    "subtitle": "Finder scan to owner alert · ordering · admin",
+    "quality_profile": "showcase"
+  },
+  "components": [
+    { "id": "finder", "type": "external", "label": "Finder", "sublabel": "QR / NFC scan", "pos": [20, 120], "size": [120, 56] },
+    { "id": "site", "type": "frontend", "label": "where-woof.com", "sublabel": "Go + HTMX · .13:3020", "pos": [200, 120], "size": [150, 56] },
+    { "id": "gate", "type": "security", "label": "Alert gate", "sublabel": "paid sub · pool · caps", "pos": [480, 120], "size": [140, 56] },
+    { "id": "sms", "type": "external", "label": "Owner SMS", "sublabel": "SMSGlobal → phone", "pos": [690, 40], "size": [140, 56] },
+    { "id": "db", "type": "database", "label": "Postgres", "sublabel": "users · tags · scans · orders", "pos": [480, 290], "size": [170, 60] },
+    { "id": "admin", "type": "backend", "label": "Admin + ordering", "sublabel": "admin.site · /order · Stripe", "pos": [200, 290], "size": [170, 60] }
+  ],
+  "boundaries": [
+    { "kind": "region", "label": "where-woof.com backend", "wraps": ["site", "gate", "db", "admin"] }
+  ],
+  "connections": [
+    { "id": "finder-site", "from": "finder", "to": "site", "label": "scan tag", "variant": "emphasis" },
+    { "id": "site-gate", "from": "site", "to": "gate", "label": "scan request", "labelDy": 44 },
+    { "id": "gate-sms", "from": "gate", "to": "sms", "label": "alert SMS", "variant": "emphasis", "fromSide": "top", "toSide": "bottom" },
+    { "id": "gate-db", "from": "gate", "to": "db", "label": "record scan", "fromSide": "bottom", "toSide": "top", "labelAt": [510, 225] },
+    { "id": "db-gate", "from": "db", "to": "gate", "label": "sub + pool", "variant": "dashed", "fromSide": "top", "toSide": "bottom", "labelAt": [500, 192] },
+    { "id": "admin-db", "from": "admin", "to": "db", "label": "orders → status", "variant": "security", "fromSide": "right", "toSide": "bottom", "labelDy": 38 },
+    { "id": "homegate", "from": "site", "to": "admin", "label": "promo / order", "variant": "dashed", "fromSide": "bottom", "toSide": "top" }
+  ]
+}
--- a/docs/where-woof-flow.mmd
+++ b/docs/where-woof-flow.mmd
@@ -0,0 +1,32 @@
+flowchart LR
+  subgraph Public["where-woof.com — public"]
+    U[Finder\nscans QR/NFC] --> T["GET /t/:code\npublic tag page"]
+    T -->|geolocation + fingerprint| SCAN["POST /t/:code/scan"]
+    T -->|finders number| FB["POST /t/:code/contact"]
+    O[Order /order\nStripe Payment Link] --> BUY[Stripe Checkout]
+    C[Contact /contact] --> MAIL[SMTP SES]
+  end
+
+  subgraph Core["Go frontend .13:3020"]
+    SCAN --> GATE{"shouldAlert\ngates"}
+    GATE -->|paid sub + SMS pool + caps| REC[record scan]
+    GATE -->|pass| SMS[SMSGlobal HTTP]
+    FB -->|dedupe| SMS2[SMSGlobal HTTP]
+  end
+
+  subgraph Admin["admin.where-woof.com — Laravel/Filament .13:3031"]
+    A[Staff manage\nusers/tags/orders/plans] --> PG
+    WH["POST /webhooks/stripe"] -->|events| ORD[orders.status + tag transitions]
+  end
+
+  subgraph Data["Postgres .13:5434"]
+    PG[(wherewoof DB\nusers tags scans\norders plans billing_events)]
+  end
+
+  SMS -->|SMS alert + map link| OWNER[Owner phone]
+  SMS2 -->|finder number| OWNER2[Owner phone]
+  BUY -->|"checkout.session.completed"| WH
+  MAIL -->|"hello@where-woof.com"| INBOX[Inbox]
+  REC --> PG
+  PG --> A
+  PG --> ORD