docs: initial set - README, PLAN, UI-SPEC, RANKING

This commit is contained in:
AlexanderRozhenko
2026-11-10 17:38:01 -04:00
commit fc3aad1e93
4 changed files with 174 additions and 0 deletions

57
docs/PLAN.md Normal file
View File

@@ -0,0 +1,57 @@
# PLAN — Bike-Tinder
**Status:** Planning (2026-11-10). Phases are gated: each lands, is verified, then the next begins. Glenn's standing rule applies — "pause" stops all spend immediately.
## v1 goal
A single-source, single-user, tailnet-only Tinder-style PWA on the Rotarran: nightly-updated catalog, swipe deck (Like / Nope / Maybe), full editable list, taste-ranked ordering.
## Phase 0 — Planning
- [x] Engineering consultation (Torres) → memo
- [x] Design docs in this repo: SOURCES, DESIGN, DATA-MODEL, RANKING, UI-SPEC
- [ ] Glenn's read on source choice + docs
- **Exit criteria:** docs merged to `main`; source decision recorded.
## Phase 1 — Data spine
- DB schema + migrations (SQLite)
- Importer: source catalog → upsert into DB (new / changed / gone states)
- Cold-start scoring wired (existing rubric logic)
- Proof: CLI query shows a ranked, deduped queue from the real live catalog
- **Exit criteria:** importer runs clean twice in a row; counts reconcile against the source; no schema surprises.
## Phase 2 — The swipe app (core)
- 2–3 UI mock variants → Glenn picks one
- API (queue, swipe, edits, filters) + PWA frontend: card stack, drag physics, Like / Nope / Maybe, match moment
- Full list view with inline edit; basic filters
- Proof: runs locally, exercised on Glenn's phone over the tailnet dev port
- **Exit criteria:** Glenn can swipe a real deck on his phone and edit results in the list.
## Phase 3 — Personalization
- Swipe history → nightly retrain of explainable ranking
- Trends panel ("you lean: …"); "because you liked X" chips
- Deck ordering by learned taste with cold-start guardrails
- **Exit criteria:** after ~30 swipes, deck order visibly reflects taste; explainability shown in UI.
## Phase 4 — Deploy + automate
- Podman compose stack at `/var/mnt/DATA/podman-stacks/bike-tinder/` + systemd unit (`Delegate=yes`)
- Tailscale serve on 9453; PWA install on Glenn's phone
- Nightly no-LLM importer cron (post-crawl); DB backup routine
- Runbook in DESIGN.md; announce + handover note
- **Exit criteria:** survives a reboot; refreshes overnight unattended; installable and used from the phone.
## Non-goals (v1)
- Multi-user accounts, social features, comments
- Additional sources (v2+); Facebook (never — manual by Glenn)
- Notifications beyond what already exists (Conduit is the house channel)
- Buying workflow (contact/inspection tracking) — possible v2
## Open decisions
- v1 source — pending consultation evidence (see `docs/SOURCES.md`)
- Mockup direction — Glenn picks at Phase 2 start