# 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).

## 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`