# Bike-Tinder A private, Tinder-style web app for browsing the motorcycle market: swipe real listings (like / nope / maybe), see everything on one editable list, and let the deck learn your taste. Built for Glenn; runs on the Rotarran, published to the tailnet only. **Status:** Phase 3 (personalization) built on `dev` (2026-11-11): sections of 25 (wildcards + second looks + new), taste engine with match points, tank gauges, dossier "Why this rank", real Trends tab, agent pass (mock / live / fallback). Phase 2 remains shipped as-is; deployment (podman stack) is Phase 4 — not started. ## How it works ``` [single-source crawler] → [nightly importer] → [app DB] → [API + PWA deck] → Glenn's thumb ↓ [swipe history] → [ranking] ``` - **Crawl** — **Kijiji** (NS + NB; decided 2026-11-10 — see `docs/SOURCES.md`) is swept nightly by the existing hunt crawler; a script-only importer folds the results in. No LLM involved, zero token cost. - **Import** — the importer upserts the source's catalog into the app database: new listings appear, changes update, vanished listings retire after repeated misses (never a blocked page, never a guess). - **Deck** — a Tinder-like PWA: card stack, drag to swipe, big buttons. Like / Nope / Maybe. "It's a match" moment when you like something. - **List & edit** — every entry in one table; re-file any call later (a nope can become a like). - **Ranking** — cold start uses the hunt's rubric score; a cheap, fully explainable swipe-boost lands first (v1.x), then a small learned model (Phase 3, retrained nightly) orders the deck by *your* taste. "Because you liked X" chips, never a black box. ## Docs - [`docs/SOURCES.md`](docs/SOURCES.md) — the v1 source decision (candidates, evidence, choice) - [`docs/DESIGN.md`](docs/DESIGN.md) — architecture, components, data flow, deployment - [`docs/DATA-MODEL.md`](docs/DATA-MODEL.md) — database schema + sync semantics - [`docs/RANKING.md`](docs/RANKING.md) — cold-start + learned ranking design - [`docs/UI-SPEC.md`](docs/UI-SPEC.md) — screens, gestures, Tinder-fidelity goals - [`docs/PLAN.md`](docs/PLAN.md) — phases, acceptance criteria, status ## Branches - `main` — stable trunk (docs + verified code); the default branch. - `dev` — active development; build work lands here first. - `release` — deployable cuts; the Rotarran stack tracks this branch. ## Run & develop Everything runs from the repo root (Python 3.13+, stdlib where possible). ```sh # one-time setup python3 -m venv .venv .venv/bin/pip install -r requirements.txt # fastapi + uvicorn (+ httpx for tests) # import the hunt state into the DB (idempotent; safe to re-run any time) python3 -m app.importer --state-dir ~/.hermes/scripts/motorcycle-hunt.d --db data/bike-tinder.sqlite3 # mirror card images into data/img/ (polite: ~1 req/s, skip-existing, resumable) .venv/bin/python -m app.imgfetch --db data/bike-tinder.sqlite3 .venv/bin/python -m app.imgfetch --limit 15 # small test runs # serve the app (127.0.0.1:9453 by default) .venv/bin/python -m app.serve --db data/bike-tinder.sqlite3 --port 9453 # self-check: P1 + P2 + P3 (25 checks, temp DB copies only) .venv/bin/python -m app.selfcheck # P3: agent pass — mock is deterministic + offline (tests, offline forge); # --live needs OPENROUTER_API_KEY (+ optional BT_AGENT_MODEL); --dry-run # validates the payload and writes nothing; --print-summary prints exactly # the strike summary a live pass would be sent. .venv/bin/python -m app.agentpass --db /tmp/bt-copy.sqlite3 --mock .venv/bin/python -m app.agentpass --db /tmp/bt-copy.sqlite3 --print-summary --dry-run # P3: run a scratch server against a COPY (NEVER point a dev server at # data/bike-tinder.sqlite3 while the live service owns it — use port 9454). cp data/bike-tinder.sqlite3 /tmp/bt-copy.sqlite3 .venv/bin/python -m app.serve --db /tmp/bt-copy.sqlite3 --img-dir data/img --port 9454 curl -s http://127.0.0.1:9454/api/section # first read composes a section curl -s -X POST http://127.0.0.1:9454/api/section/forge \ -H 'Content-Type: application/json' -d '{"size": 8}' # mock pass + compose # proof CLI: ranked deck + counts (read-only) python3 -m app.deck --db data/bike-tinder.sqlite3 --top 15 ``` Key routes: `/` (PWA), `/api/health`, `/api/stats`, `/api/deck?limit=&cursor=` (read-only legacy fallback), `POST /api/swipe` / `DELETE /api/swipe/{id}`, `/api/list?decision=&sort=&q=&limit=&offset=`, `/api/listing/{id}`, `POST /api/import`, `POST /api/badge/seen`, `/img/{id}` (cached file → 302 source CDN → 404 placeholder). P3 (Phase 3): `GET /api/section`, `POST /api/section/forge` `{size}`, `GET /api/trends`, `POST /api/agent/run` `{source: mock|live}`, `POST /api/prefs` `{key: forge_mode, value: ondemand|strict}`. Listing payloads carry `points`, `tank {value, band}`, `slot`, `round_next`, `points_breakdown`. Full contract: `docs/UI-SPEC.md` §10 + `docs/RANKING.md` Stage 2 + the task brief. `data/` and `.venv/` are gitignored — the DB, image mirror and venv are local state. ## Deployment (planned) A small podman compose stack on the Rotarran under `/var/mnt/DATA/podman-stacks/bike-tinder/`, its own systemd user unit (`Delegate=yes`), SQLite database. The stack ships its own Tailscale node (sidecar container — no host-tailnet coupling) and serves the app privately at `https://biketinder.tailf35a34.ts.net`. Single user; reachable only from Glenn's own devices. ## Crew - **Glenn** — owner; the thumb that swipes. - **Alex** — resident agent; architecture, orchestration, docs. - **Torres** — engineer; builds and maintains this repo.