docs: architecture, toolchain, resume highlights; AGENTS.md points to them

docs/ARCHITECTURE.md

@@ -0,0 +1,68 @@
+# Where Woof — Architecture
+
+How the system ties together, where everything runs, and how data flows.
+
+## Systems at a glance
+
+```
+                          ┌─────────────────────────────────────────────────┐
+   Finder scans tag ──►    │  where-woof.com / www / .home.lab (public)      │
+   (QR / NFC → URL)        │  Caddy (.35, TLS) ──► .13:3020                  │
+                           │  GOAT frontend (Go + HTMX + Alpine + Tailwind)  │
+                           │  systemd user service `where-woof`              │
+                           └───────────────────┬─────────────────────────────┘
+                                               │ same Postgres
+                           ┌───────────────────▼─────────────────────────────┐
+   Staff manage ──►         │  admin.where-woof.com / www.admin (staff)       │
+                           │  Caddy (.35, TLS) ──► .13:3031                   │
+                           │  Laravel + Filament admin (Docker)               │
+                           └───────────────────┬─────────────────────────────┘
+                                               │
+                           ┌───────────────────▼─────────────────────────────┐
+                           │  Postgres 16 `wherewoof-db` (.13:5434)          │
+                           │  tables: users, tags, scans, products, orders   │
+                           └─────────────────────────────────────────────────┘
+```
+
+- **Public path**: tag QR/NFC → `where-woof.com/t/<id>` → Caddy on `.35` → Go app on `.13:3020` → Postgres on `.13:5434`. Geolocation + alerts send SMS via SMSGlobal HTTP API.
+- **Admin path**: staff → `admin.where-woof.com` → Caddy → Laravel/Filament on `.13:3031` (Docker) → the **same** Postgres.
+- **Single source of truth**: one database, two apps. `db/schema.sql` is canonical (Laravel reads the existing tables via Eloquent; migration ownership moves to Laravel later).
+
+## Where things run
+
+| Machine | Role | Runs |
+|---|---|---|
+| **.27** (desktop) | Dev | Go frontend (`make run`, :3020), Laravel admin (Docker, :3030) — dev copies; build machine for the Go binary |
+| **.13** (server) | Production | `wherewoof-db` Postgres (Docker, :5434), frontend (systemd user service `where-woof`, :3020), Laravel admin (Docker, :3031) |
+| **.35** (caddy) | Reverse proxy | Caddy — TLS termination for all public domains |
+| Router | Public entry | Port-forwards 80/443 → .35; DNS A records → `144.6.86.11` |
+| InMotion | DNS/legacy | `where-woof.com` zone — A records → router IP (legacy site retired) |
+
+## Data model (v2 + additions)
+
+- `users` — owners + admins (`is_admin`), `password_hash`, `remember_token`
+- `tags` — the registry: `tag_code` (opaque AES-256-encrypted sequential IDs 0–99), status unset/active/suspended, owner, item details, `sms_enabled`, `product_id`, `order_id`
+- `scans` — every tag visit: lat/lng, `location_shared`, `scanner_phone`, `alert_sent`, `fingerprint`
+- `products` — product templates (sku, name, item type)
+- `orders` — sales: status pending/paid/lapsed/cancelled, linked to tags
+
+## Key flows
+
+1. **Claim**: owner registers → adds `tag_code` → must exist in registry (anti-scam) → edits details → status `active`.
+2. **Scan**: finder opens `/t/<code>` → JS geolocation + fingerprint → POST scan → recorded → alert decision (sms_enabled → fingerprint 24 h block → 10-min/250 m throttle → different-finder rule) → SMS to owner via SMSGlobal HTTP API (pooled/verified number).
+3. **Contact**: finder leaves number → stored on scan → owner SMS'd (deduped).
+4. **Admin**: manage users/tags/products/orders; assign tag → product/order; suspend; dashboard stats.
+
+## Security & anti-abuse
+
+- Registry-only tag codes (preset IDs; case-sensitive; no user-created codes).
+- Location-aware alert throttle (250 m / 10 min), different-finder re-alert, 24 h device fingerprint block.
+- Sessions: signed cookies (Go), Laravel sessions (admin); bcrypt passwords.
+- SMS cost protection via the above + per-tag `sms_enabled` kill-switch.
+
+## Deployment
+
+- Frontend: `make build` on .27 → rsync to `.13:/var/www/where-woof` → systemd restart.
+- 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).