89 lines
4.2 KiB
Markdown
89 lines
4.2 KiB
Markdown
# Where Woof — Return-Tag Platform
|
|
|
|
Find your woof. A return-item tag platform (PetHub/ReturnMe style) — *"Where Woof !"* (a play on *werewolf*). Pre-coded QR/NFC tags on your dog, baggage, skis, etc. A finder scans the tag and sees exactly how to return it — call, text, or leave their number; location is shared with the owner when the finder allows.
|
|
|
|
## Structure at a glance
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph public["where-woof.com — public (Go + HTMX)"]
|
|
T[Tag QR/NFC] --> P["GET /t/:code"]
|
|
P --> S["POST /t/:code/scan"]
|
|
P --> C[finder contact]
|
|
O[/order/] --> BUY[Stripe Checkout]
|
|
end
|
|
subgraph admin["admin.where-woof.com — Laravel + Filament"]
|
|
A[Staff manage users/tags/orders/plans]
|
|
W["POST /webhooks/stripe"] --> D2["orders.status + tag transitions"]
|
|
end
|
|
subgraph core["Go frontend .13:3020"]
|
|
S --> G{"shouldAlert <br/> paid sub · SMS pool · caps"}
|
|
G -->|pass| SMS["SMSGlobal → owner phone"]
|
|
G -->|record| DB["Postgres .13:5434"]
|
|
end
|
|
BUY --> W
|
|
A --> DB
|
|
DB --> D2
|
|
```
|
|
|
|
*Interactive map:* [maps.lab.audasmedia.com.au/where_woof/docs/](https://maps.lab.audasmedia.com.au/where_woof/docs/diagrams/where-woof-flow.html) · *Source:* `docs/where-woof-flow.mmd`
|
|
|
|
## Status
|
|
|
|
GOAT front-end (Phase 1) built and verified — see `where_woof.md` for the full plan and roadmap.
|
|
|
|
- Plan: [where_woof.md](where_woof.md), [awesome-design.md](awesome-design.md)
|
|
- Specs & changes: `openspec/` (frontend-foundation ✅, scan-flow ✅)
|
|
- Front-end: `frontend/` (Go + HTMX + Alpine + Tailwind + Postgres)
|
|
- Mockups: `mockups/`
|
|
|
|
## Testing the site (dev)
|
|
|
|
Everything runs from this repo on `.27`. SMS is in **log mode** by default — no real SMS is sent until SMSGlobal credentials are set; instead you'll see `SMS to …` lines in the server log.
|
|
|
|
### 1. Start it
|
|
|
|
```bash
|
|
make db-up # apply schema (idempotent — safe to re-run)
|
|
make seed # insert 25 test tags: TEST000001 .. TEST000025
|
|
make run # http://localhost:3020
|
|
```
|
|
|
|
### 2. Create an account (fill in the form)
|
|
|
|
Click **Register** (top right) → name, email, password (≥ 8 characters). You're logged in automatically and land on **My Tags**.
|
|
|
|
### 3. Claim a tag (owner side — the form)
|
|
|
|
- On **My Tags**, enter a code like `TEST000001` → **Add tag**. It appears as *Unset*.
|
|
- Click **Edit** and fill the form: item type (Dog), description (e.g. Shadow), photo URL, **phone number (e.g. +61423274487)**, address, notes, and the *Send me SMS alerts* checkbox. Save → status becomes *Active*.
|
|
|
|
### 4. The finder experience (the URL that works)
|
|
|
|
Open **http://localhost:3020/t/TEST000001** in a **private/incognito window** (that's the finder — no login):
|
|
|
|
- It asks for your location → **Allow**. Watch the server log — an `SMS to` line appears with the map link.
|
|
- Deny instead → the page still works, and a **“Re-check my location”** button appears; click it and allow to send the location after all.
|
|
- **Send an SMS** link → opens your phone's SMS app with the owner's number prefilled.
|
|
- **Leave your number** → submit a mobile → the owner gets an SMS with the finder's number (also stored on the scan).
|
|
|
|
### 5. Throttle behaviour (repeat scans)
|
|
|
|
- Scan the same tag at the same location twice within 10 minutes → only **one** SMS.
|
|
- Scan again from > 250 m away within the window → a **second** SMS (it moved).
|
|
- Wait 10+ minutes → the next scan alerts again.
|
|
|
|
### 6. Info-only tag
|
|
|
|
Uncheck *Send me SMS alerts* on the edit form → scans are recorded but no SMS is sent.
|
|
|
|
### 7. Watching the SMS
|
|
|
|
In log mode: `tail -f /tmp/ww-server.log` and look for `SMS to`. With real credentials set, the owner's phone receives the text — set `SMS_USER`/`SMS_PASSWORD`/`SMS_FROM` (SMSGlobal HTTP API, `from` = your verified number like `61423274487`) when running `make run`.
|
|
|
|
### Notes
|
|
|
|
- **Geolocation requires HTTPS** except on `localhost` — testing on a phone over the LAN needs the Caddy/TLS deployment (Phase 7) or `localhost`.
|
|
- Reset the database any time: `make db-up` re-applies the schema (idempotent); drop the `wherewoof-db` container volume for a truly fresh start.
|
|
- Automated suites live in `/tmp/verify.sh` (Phase 1, 22 checks) and `/tmp/verify2.sh` (Phase 2, 19 checks) — they reset the DB themselves.
|