diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 5f8dfcc..65f54e2 100644 --- 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` diff --git a/docs/diagrams/where-woof-flow.html b/docs/diagrams/where-woof-flow.html new file mode 100644 index 0000000..c295fed --- /dev/null +++ b/docs/diagrams/where-woof-flow.html @@ -0,0 +1,13619 @@ + + + + + + + Where Woof — where-woof.com flow Diagram + + + + + + + + + + + +
+ +
+
+
+

Where Woof — where-woof.com flow

+
+

Finder scan to owner alert · ordering · admin

+
+ + + + + + +
+ + Where Woof — where-woof.com flow + Finder scan to owner alert · ordering · admin + + + + + + + + + + + + + + + + + + + + + + + + + where-woof.com backend + + + + + + + + + + + + + Finder · QR / NFC scan · Architecture component + + + + Finder + QR / NFC scan + + + + where-woof.com · Go + HTMX · .13:3020 · where-woof.com backend + + + + where-woof.com + Go + HTMX · .13:3020 + + + + Alert gate · paid sub · pool · caps · where-woof.com backend + + + + Alert gate + paid sub · pool · caps + + + + Owner SMS · SMSGlobal → phone · Architecture component + + + + Owner SMS + SMSGlobal → phone + + + + Postgres · users · tags · scans · orders · where-woof.com backend + + + + Postgres + users · tags · scans · orders + + + + Admin + ordering · admin.site · /order · Stripe · where-woof.com backend + + + + Admin + ordering + admin.site · /order · Stripe + + + + + + scan tag + + + + scan request + + + + alert SMS + + + + record scan + + + + sub + pool + + + + orders → status + + + + promo / order + + + + + Legend + + + Frontend + + + + Backend + + + + Database + + + + Security + + + + External + + + +

+ + + + + + + + +
+ + +
+ +
+ +
+ + + + diff --git a/docs/diagrams/where-woof-flow.png b/docs/diagrams/where-woof-flow.png new file mode 100644 index 0000000..3538542 Binary files /dev/null and b/docs/diagrams/where-woof-flow.png differ diff --git a/docs/diagrams/where-woof-flow.svg b/docs/diagrams/where-woof-flow.svg new file mode 100644 index 0000000..19714ad --- /dev/null +++ b/docs/diagrams/where-woof-flow.svg @@ -0,0 +1 @@ +

admin.where-woof.com — Laravel/Filament .13:3031

Go frontend .13:3020

where-woof.com — public

geolocation + fingerprint

finders number

paid sub + SMS pool + caps

pass

dedupe

events

SMS alert + map link

finder number

checkout.session.completed

hello@where-woof.com

Postgres .13:5434

Finder
scans QR/NFC

GET /t/:code
public tag page

POST /t/:code/scan

POST /t/:code/contact

Order /order
Stripe Payment Link

Stripe Checkout

Contact /contact

SMTP SES

shouldAlert
gates

record scan

SMSGlobal HTTP

SMSGlobal HTTP

Staff manage
users/tags/orders/plans

wherewoof DB
users tags scans
orders plans billing_events

POST /webhooks/stripe

orders.status + tag transitions

Owner phone

Owner phone

Inbox

 \ No newline at end of file diff --git a/docs/diagrams/where-woof-flow.visual-check.1440x900.dark.png b/docs/diagrams/where-woof-flow.visual-check.1440x900.dark.png new file mode 100644 index 0000000..4b6abdc Binary files /dev/null and b/docs/diagrams/where-woof-flow.visual-check.1440x900.dark.png differ diff --git a/docs/diagrams/where-woof-flow.visual-check.1440x900.light.png b/docs/diagrams/where-woof-flow.visual-check.1440x900.light.png new file mode 100644 index 0000000..8a6de01 Binary files /dev/null and b/docs/diagrams/where-woof-flow.visual-check.1440x900.light.png differ diff --git a/docs/diagrams/where-woof-flow.visual-check.2048x1320.dark.png b/docs/diagrams/where-woof-flow.visual-check.2048x1320.dark.png new file mode 100644 index 0000000..480530c Binary files /dev/null and b/docs/diagrams/where-woof-flow.visual-check.2048x1320.dark.png differ diff --git a/docs/diagrams/where-woof-flow.visual-check.2048x1320.light.png b/docs/diagrams/where-woof-flow.visual-check.2048x1320.light.png new file mode 100644 index 0000000..7a22cf6 Binary files /dev/null and b/docs/diagrams/where-woof-flow.visual-check.2048x1320.light.png differ diff --git a/docs/diagrams/where-woof-flow.visual-check.html b/docs/diagrams/where-woof-flow.visual-check.html new file mode 100644 index 0000000..5b6ddaf --- /dev/null +++ b/docs/diagrams/where-woof-flow.visual-check.html @@ -0,0 +1,32 @@ + + + + + +Archify visual-check · where-woof-flow.html + + + +

Archify visual-check

where-woof-flow.html · automated containment pass · visual review pending

+
+
+ light 1440 by 900 +
LIGHT · 1440×900 · containment pass
+
+
+ dark 1440 by 900 +
DARK · 1440×900 · containment pass
+
+
+ light 2048 by 1320 +
LIGHT · 2048×1320 · containment pass
+
+
+ dark 2048 by 1320 +
DARK · 2048×1320 · containment pass
+
+
+ + diff --git a/docs/diagrams/where-woof-flow.visual-check.json b/docs/diagrams/where-woof-flow.visual-check.json new file mode 100644 index 0000000..518c4c2 --- /dev/null +++ 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" + } +} diff --git a/docs/where-woof-archify.json b/docs/where-woof-archify.json new file mode 100644 index 0000000..2fbc168 --- /dev/null +++ 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" } + ] +} \ No newline at end of file diff --git a/docs/where-woof-flow.mmd b/docs/where-woof-flow.mmd new file mode 100644 index 0000000..71f3cc6 --- /dev/null +++ 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 \ No newline at end of file