Compare commits
6 Commits
35138bdc22
...
dev
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
e1f06e3405 | ||
|
|
f4ebd33329 | ||
|
|
beeace231d | ||
|
|
79e7a4f61f | ||
|
|
618cd4a61c | ||
|
|
66d3cc4da3 |
145
README.md
145
README.md
@@ -1,142 +1,19 @@
|
||||
# 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.
|
||||
Find your next motorcycle without sorting through the same classifieds every night. Bike-Tinder is a private, self-hosted web app that puts motorcycle listings from Kijiji in Nova Scotia and New Brunswick into a photo-first swipe deck.
|
||||
|
||||
**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) shipped 2026-11-12 — stack live under `podman-stack-bike-tinder.service`, nightly import + agent read + DB backup armed; the private phone URL (`https://biketinder.tailf35a34.ts.net`) awaits the one-time Tailscale sidecar authorization.
|
||||
Swipe right to like a bike, left to pass, or up if you're on the fence. Open a card to check the price, mileage, and photos. The searchable List lets you revisit a bike or change your mind later. As you swipe, the deck learns what you tend to like and brings more of those bikes forward.
|
||||
|
||||
**B1 (photo experience v2)** built on `dev`: full photo galleries mirrored locally, deck flips (tap left/right thirds, clamped), segment bars, a fullscreen viewer (swipe nav, pinch/double-tap zoom, pull-down close), and repeat rotation (a re-shown card leads at its next photo). See UI-SPEC §11 + the "B1 develop notes" section below.
|
||||
## A look at the app
|
||||
|
||||
## How it works
|
||||
| Swipe deck | Bike details |
|
||||
| :---: | :---: |
|
||||
|  |  |
|
||||
|
||||
```
|
||||
[single-source crawler] → [nightly importer] → [app DB] → [API + PWA deck] → Glenn's thumb
|
||||
↓
|
||||
[swipe history] → [ranking]
|
||||
```
|
||||
*Screenshots from the app with demo listings.*
|
||||
|
||||
- **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.
|
||||
## Documentation
|
||||
|
||||
## 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.
|
||||
|
||||
## B1 develop notes (photo experience v2)
|
||||
|
||||
- **Columns** (guarded in `db.init_db`): `listings.imgs TEXT` (JSON array of
|
||||
gallery URLs, page order; entry 0 = the primary = `img_url`) ·
|
||||
`swipes.last_photo_idx INTEGER` (photo on screen at swipe time; drives §11.5
|
||||
rotation `(last+1) % n`; NULL = photo 0).
|
||||
- **Importer** copies the hunt state's `imgs[]` into `listings.imgs`; `img_url`
|
||||
stays the state `img` and falls back to `imgs[0]`. Re-imports are
|
||||
byte-stable (selfcheck proves it on the 640-row copy).
|
||||
- **Route:** `GET /img/{id}?i=n` — mirrored file → CDN 302 → 404. `i=0`
|
||||
(default) keeps the legacy chain (`{id}.webp`, then `{id}_0.webp`, then
|
||||
`img_url`); `i>0` serves `{id}_{n}.webp` with the CDN fallback from
|
||||
`imgs[n]`. Out-of-range/unknown → 404.
|
||||
- **Mirror:** `app/imgfetch.py` downloads every `imgs[n]`. The primary (n=0)
|
||||
lands at the legacy `data/img/{id}.webp` (one canonical file — no duplicate
|
||||
fetch); extras land at `data/img/{id}_{n}.webp`. Same politeness as P2
|
||||
(~1 req/s, skip-existing, `.part`-atomic, per-file CLI progress).
|
||||
- **Payload:** deck/section/list/listing items add `n_photos` (int) and
|
||||
`last_photo_idx` (int|null). `POST /api/swipe` accepts optional `photo_idx`
|
||||
(non-negative int; persisted; absent key preserves, explicit null clears).
|
||||
- **Frontend:** tap LEFT/RIGHT third = photo flip (clamped, no wrap, commits
|
||||
nothing), CENTER third = fullscreen viewer (ⓘ still wins); segment bars per
|
||||
photo (Tinder-style; band chips drop to `top:22px` when segments exist);
|
||||
viewer = swipe nav + pinch 1×–4× + double-tap 1×↔2.5× + ✕/pull-down close
|
||||
(returns to the same card/photo); re-shown cards lead at `(last+1) % n`;
|
||||
preloads the top card's next photo + next card's lead; `sw.js` cache is
|
||||
`bike-tinder-v3`.
|
||||
- **FE walk (evidence):** `app/fe_walk_b1.py` — deterministic, headless:
|
||||
|
||||
```sh
|
||||
.venv/bin/python -m app.fe_walk_b1 setup # fixtures: copy DB + 701-706 synthetics + local photos
|
||||
env -u OPENROUTER_API_KEY .venv/bin/python -m app.serve \
|
||||
--db /var/home/admin/dev/bike-tinder-b1/test-walk.sqlite3 \
|
||||
--img-dir /var/home/admin/dev/bike-tinder-b1/test-img \
|
||||
--host 127.0.0.1 --port 9454 # scratch server (mock forge)
|
||||
.venv/bin/python -m app.fe_walk_b1 # 390 DOM checks
|
||||
```
|
||||
- **Test data:** `b1/test-state/` = hunt-state sample with `imgs` (8/3-photo
|
||||
galleries; refresh `fetched_at` before an import gate test) ·
|
||||
`b1/test-img/` = staged `{id}_{n}.webp` photos · `b1/test-copy.sqlite3` =
|
||||
pristine live-DB snapshot (selfcheck copies it; never write to it).
|
||||
|
||||
## 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.
|
||||
- [How it works](docs/HOW-IT-WORKS.md) — catalog, swipe history, and ranking
|
||||
- [Development and deployment](docs/DEVELOPMENT.md) — local setup, tests, and operations
|
||||
- [Interface and gestures](docs/UI-SPEC.md) · [Roadmap](docs/PLAN.md)
|
||||
|
||||
@@ -544,6 +544,33 @@ def walk_rich():
|
||||
and ('%d fresh' % stats['fresh']) in pill_txt,
|
||||
'item 7: pill reads live + fresh (%s)' % pill_txt.replace('\n', ' '))
|
||||
|
||||
# --- v1.1.1 (issue #2): the header pill keeps itself live --------------
|
||||
pl0 = api('/api/stats')
|
||||
key('ArrowRight') # probe swipe, undone right after
|
||||
flick(300)
|
||||
pl1 = api('/api/stats')
|
||||
dl = time.time() + 5
|
||||
ptx = ''
|
||||
while time.time() < dl:
|
||||
ptx = page.evaluate("() => document.getElementById('pill').textContent")
|
||||
if ('%d fresh' % pl1['fresh']) in ptx:
|
||||
break
|
||||
time.sleep(0.2)
|
||||
check(('%d fresh' % pl1['fresh']) in ptx and ('%d live' % pl1['live']) in ptx,
|
||||
'issue #2: pill refreshes itself after a swipe, no reload (%s -> %s)'
|
||||
% (pl0['fresh'], ptx))
|
||||
key('ArrowDown') # undo the probe swipe (net-zero)
|
||||
flick(300)
|
||||
pl2 = api('/api/stats')
|
||||
dl = time.time() + 5
|
||||
while time.time() < dl:
|
||||
ptx = page.evaluate("() => document.getElementById('pill').textContent")
|
||||
if ('%d fresh' % pl2['fresh']) in ptx:
|
||||
break
|
||||
time.sleep(0.2)
|
||||
check(('%d fresh' % pl2['fresh']) in ptx,
|
||||
'issue #2: pill refreshes itself after an undo, no reload (%s)' % ptx)
|
||||
|
||||
# --- B1 no-lock: rapid commit storm (no sheet, no lock) ----------------
|
||||
before = sect_pill()['txt']
|
||||
taps(2, 40)
|
||||
|
||||
@@ -934,6 +934,10 @@ def test_p3_points_and_band():
|
||||
br = eng.breakdown(1)
|
||||
assert {b['source'] for b in br} <= {'rubric', 'taste', 'agent'}
|
||||
assert br[0]['source'] == 'rubric'
|
||||
# regression (#3): a listing OUTSIDE the engine's pool (delisted
|
||||
# mid-batch, never swiped) must degrade quietly, not crash the render
|
||||
assert eng.points(9999) is None
|
||||
assert eng.breakdown(9999) == []
|
||||
|
||||
|
||||
def test_p3_payload_additions():
|
||||
@@ -959,6 +963,39 @@ def test_p3_payload_additions():
|
||||
shutil.rmtree(d, ignore_errors=True)
|
||||
|
||||
|
||||
def test_issue3_section_survives_midsection_delist():
|
||||
"""#3 regression: one card delisted after compose must not 500 the deck.
|
||||
|
||||
The section render asks the taste engine for a breakdown of every
|
||||
card. A listing that left the active pool mid-batch AND has no swipe
|
||||
history is not in the engine's by_id map; the unguarded lookup used
|
||||
to raise, killing GET /api/section and GET /api/listing/{id} with a
|
||||
500 (live incident 2026-11-15: section 57 + delisted listing 298).
|
||||
"""
|
||||
d, c, db_path = p3_env()
|
||||
try:
|
||||
sec = c.get('/api/section')
|
||||
assert sec.status_code == 200, sec.status_code
|
||||
body = sec.json()
|
||||
conn = _sq_conn(db_path)
|
||||
ev_ids = {r['listing_id'] for r in conn.execute(
|
||||
'SELECT DISTINCT listing_id FROM swipe_events')}
|
||||
it = next((x for x in body['items'] if x['id'] not in ev_ids), None)
|
||||
assert it is not None, 'fixture section has no unswiped card'
|
||||
conn.execute("UPDATE listings SET status='gone' WHERE id=?",
|
||||
(it['id'],))
|
||||
conn.commit()
|
||||
conn.close()
|
||||
r = c.get('/api/section')
|
||||
assert r.status_code == 200, r.status_code
|
||||
assert it['id'] in [x['id'] for x in r.json()['items']]
|
||||
one = c.get('/api/listing/%d' % it['id'])
|
||||
assert one.status_code == 200, one.status_code
|
||||
assert one.json()['points_breakdown'] == []
|
||||
finally:
|
||||
shutil.rmtree(d, ignore_errors=True)
|
||||
|
||||
|
||||
# --- B1 checks (photo experience v2, UI-SPEC §11 / DATA-MODEL B1) -----------
|
||||
|
||||
def make_b1_item(title, imgs=None, img=None, price='$5,000', km='8000'):
|
||||
@@ -1751,6 +1788,8 @@ P3_API_TESTS = [
|
||||
('p3: agentpass mock determinism + live fallback', test_p3_agentpass_mock_and_fallback),
|
||||
('p3: points/band function known answers', test_p3_points_and_band),
|
||||
('p3: payload additions (list/listing/section)', test_p3_payload_additions),
|
||||
('p3: mid-section delist keeps the deck up (#3)',
|
||||
test_issue3_section_survives_midsection_delist),
|
||||
]
|
||||
|
||||
|
||||
|
||||
@@ -415,6 +415,7 @@ function setDecision(id, act, secId=null, photoIdx=null){
|
||||
localDecisions.set(id, act);
|
||||
updateRowDecision(id, act); // optimistic paint
|
||||
enqueue(id, act, secId, photoIdx);
|
||||
refreshStats(); // v1.1.1 (#2): every decision change nudges the header counters
|
||||
}
|
||||
|
||||
/* ---------- payload -> display helpers ---------- */
|
||||
@@ -660,6 +661,7 @@ async function loadSection(){
|
||||
buffer.push(...fresh);
|
||||
fillPile();
|
||||
updateSectionUI(body);
|
||||
refreshStats(); // v1.1.1 (#2): a new batch landed — freshen the counters
|
||||
}catch(e){ setTimeout(()=>loadSection(),15000); }
|
||||
finally{ deckLoading=false; }
|
||||
maybeRefill();
|
||||
@@ -879,19 +881,20 @@ function closeDetail(){ const d=$('detail'); d.style.transition=''; d.style.tran
|
||||
$('dclose').onclick=closeDetail;
|
||||
$('dclose').addEventListener('pointerdown',e=>e.stopPropagation());
|
||||
/* pull-down-to-close (grabber bar + photo) */
|
||||
let dDragY=null;
|
||||
function dStart(e){ dDragY=e.clientY; $('detail').style.transition='none'; try{e.currentTarget.setPointerCapture(e.pointerId)}catch(_){} }
|
||||
let dDragY=null, heroTapped=false;
|
||||
function dStart(e){ heroTapped=false; dDragY=e.clientY; $('detail').style.transition='none'; try{e.currentTarget.setPointerCapture(e.pointerId)}catch(_){} }
|
||||
function dMoveH(e){ if(dDragY===null) return; const dy=Math.max(0,e.clientY-dDragY); $('detail').style.transform=`translateY(${dy}px)`; }
|
||||
function dEndH(e){ if(dDragY===null) return; const dy=Math.max(0,e.clientY-dDragY); dDragY=null;
|
||||
if(dy>110){ closeDetail(); }
|
||||
else { const d=$('detail'); d.style.transition='transform .25s cubic-bezier(.2,.8,.3,1)'; d.style.transform='';
|
||||
/* B1 §11.3: a tap on the dossier HERO opens the fullscreen viewer at
|
||||
photo 0. When the dossier sits over the deck, the viewer back-chain
|
||||
walks Esc back to the dossier (item 2), then to the deck. */
|
||||
if(e.type==='pointerup' && dy<=6 && e.currentTarget&&e.currentTarget.classList
|
||||
&& e.currentTarget.classList.contains('dhero') && dData&&dData.img){
|
||||
openViewer(dData,0,{type:'dossier', backToDetail:dEntry});
|
||||
} } }
|
||||
heroTapped=e.type==='pointerup' && dy<=6 && e.currentTarget.classList.contains('dhero');
|
||||
} }
|
||||
/* Open on the completed click. Opening on touch pointerup puts the new
|
||||
backdrop under the finger just in time to receive the same tap's click. */
|
||||
document.querySelector('.dhero').addEventListener('click',()=>{
|
||||
if(heroTapped && dData && dData.img) openViewer(dData,0,{type:'dossier', backToDetail:dEntry});
|
||||
heroTapped=false;
|
||||
});
|
||||
[document.querySelector('.dgrab'),document.querySelector('.dhero')].forEach(el=>{ if(!el) return; el.addEventListener('pointerdown',dStart); el.addEventListener('pointermove',dMoveH); el.addEventListener('pointerup',dEndH); el.addEventListener('pointercancel',dEndH); });
|
||||
function dAction(a){
|
||||
const ctx=dCtx; closeDetail();
|
||||
@@ -1082,10 +1085,14 @@ function renderList(){
|
||||
}
|
||||
/* optimistic decision updates for whichever screens show this listing */
|
||||
function updateRowDecision(id, act){
|
||||
const find=[listItems];
|
||||
for(const arr of find){
|
||||
const it=arr.find(x=>x.id===id);
|
||||
if(it) it.decision=act;
|
||||
const it=listItems.find(x=>x.id===id);
|
||||
if(it){
|
||||
it.decision=act;
|
||||
if(listCtl.decision!=='all' && listCtl.decision!==(act||'undecided')){
|
||||
listItems=listItems.filter(x=>x!==it);
|
||||
$('lrows').querySelector(`.row[data-i="${id}"]`)?.remove();
|
||||
if(!listItems.length) renderList(); // existing empty state
|
||||
}
|
||||
}
|
||||
const el=$('lrows').querySelector(`.rc[data-i="${id}"]`);
|
||||
if(el) el.querySelectorAll('.rbtn').forEach(b=>b.classList.toggle('on',b.dataset.s===act));
|
||||
@@ -1112,7 +1119,6 @@ $('lrows').addEventListener('click',e=>{
|
||||
if(!it) return;
|
||||
const next= it.decision===s?null:s; // tapping the lit button clears
|
||||
setDecision(id,next);
|
||||
if(next===null && (listCtl.decision===s)) renderList(); // row leaves a filtered view
|
||||
});
|
||||
$('fdec').addEventListener('click',e=>{
|
||||
const chip=e.target.closest('.fchip'); if(!chip) return;
|
||||
@@ -1206,6 +1212,19 @@ async function loadStats(){
|
||||
fetch('/api/badge/seen',{method:'POST'}).catch(()=>{});
|
||||
}
|
||||
}
|
||||
/* v1.1.1 (issue #2): loadStats only ran at boot, so the header pill and the
|
||||
list sub-line went stale after every swipe until a full reload. Refresh
|
||||
shortly after any decision change (swipes, undo, dossier/list/matches
|
||||
edits) and whenever a new batch lands. Coalesced + fire-and-forget: a
|
||||
swipe never waits on it. */
|
||||
let statsTimer=null;
|
||||
function refreshStats(){
|
||||
if(statsTimer) return; // bursts collapse into one read
|
||||
statsTimer=setTimeout(()=>{ statsTimer=null; loadStats(); },600);
|
||||
}
|
||||
/* foreground/resume: catch anything that changed while the app slept
|
||||
(e.g. the 08:30 import) without waiting for the next swipe */
|
||||
document.addEventListener('visibilitychange',()=>{ if(!document.hidden) refreshStats(); });
|
||||
|
||||
/* ---------- P3 section UI: progress pill + report + forge + modes ---------- */
|
||||
let sectDecided=0, sectTotal=0;
|
||||
@@ -1297,6 +1316,7 @@ $('btnForge').onclick=async()=>{
|
||||
buffer.push(...fresh);
|
||||
fillPile();
|
||||
updateSectionUI(body);
|
||||
refreshStats(); // v1.1.1 (#2): forged batch — freshen the counters
|
||||
if(pile.length){ $('report').classList.remove('on'); }
|
||||
// item 8: a zero-item forge on a fully drained catalog -> empty2,
|
||||
// no lone Forge button inviting a wasted agent run
|
||||
|
||||
@@ -379,8 +379,13 @@ class TasteEngine:
|
||||
"""Source-labeled breakdown lines for the dossier."""
|
||||
row = self.by_id.get(listing_id)
|
||||
lines = []
|
||||
lines.append({'source': 'rubric', 'label': 'rubric fit',
|
||||
'value': int(row['score'] or 0)})
|
||||
# issue #3: a section can outlive an ad. A listing that left the
|
||||
# active pool mid-batch (and has no swipe history) is not in
|
||||
# by_id; its breakdown degrades to no-signal lines instead of a
|
||||
# TypeError that would 500 the whole section render.
|
||||
if row is not None:
|
||||
lines.append({'source': 'rubric', 'label': 'rubric fit',
|
||||
'value': int(row['score'] or 0)})
|
||||
for label, s, _d, _v in self.contributions(listing_id)[:3]:
|
||||
lines.append({'source': 'taste', 'label': label,
|
||||
'value': round(s, 1)})
|
||||
|
||||
42
docs/DEVELOPMENT.md
Normal file
42
docs/DEVELOPMENT.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Development and deployment
|
||||
|
||||
Run these commands from the repo root. The container uses Python 3.14. Use a scratch database and a different port from any running instance; the example binds only to localhost.
|
||||
|
||||
```sh
|
||||
python3 -m venv .venv
|
||||
.venv/bin/python -m pip install -r requirements.txt
|
||||
mkdir -p data/dev-img
|
||||
|
||||
# Optional: seed a development catalog from motorcycle-hunt snapshots.
|
||||
.venv/bin/python -m app.importer --state-dir /path/to/hunt-snapshots --db data/dev.sqlite3
|
||||
|
||||
# Local app and read-only deck preview.
|
||||
.venv/bin/python -m app.serve --host 127.0.0.1 --port 9454 --db data/dev.sqlite3 --img-dir data/dev-img
|
||||
.venv/bin/python -m app.deck --db data/dev.sqlite3 --top 15
|
||||
|
||||
# Run separately from the dev server.
|
||||
.venv/bin/python -m app.selfcheck
|
||||
```
|
||||
|
||||
`data/` and `.venv/` are local and ignored by Git. The `app.imgfetch` CLI can cache images for a development catalog; use `--help` for options. The nightly process in the live stack imports the catalog, refreshes the taste profile, and backs up SQLite.
|
||||
|
||||
For an offline taste-profile pass, run `app.agentpass --mock` against a development database with swipe history. To inspect the inputs without writing a profile, use `--print-summary --dry-run`. The optional live provider is configured outside the repo. Never use the running instance's DB for test writes; use SQLite's backup API if you need a consistent copy of a database in use. The legacy browser walks (`app.fe_walk_b1`, `app.fe_walk_v11`) need Playwright, Chromium, and staged scratch fixtures; inspect their fixture paths before running them.
|
||||
|
||||
## API entry points
|
||||
|
||||
| Area | Routes |
|
||||
| --- | --- |
|
||||
| Status | `GET /api/health`, `GET /api/stats` |
|
||||
| Browse | `GET /api/section`, `GET /api/list`, `GET /api/listing/{id}` |
|
||||
| Decide | `POST /api/swipe`, `DELETE /api/swipe/{id}` |
|
||||
| Refresh | `POST /api/import`, `POST /api/section/forge`, `POST /api/agent/run` |
|
||||
| Preferences | `POST /api/prefs`, `POST /api/badge/seen` |
|
||||
| Display | `GET /api/trends`, `GET /img/{id}?i=n` |
|
||||
|
||||
For data contracts, see [Data model](DATA-MODEL.md), [Ranking](RANKING.md), and the [UI spec](UI-SPEC.md).
|
||||
|
||||
## Deployment
|
||||
|
||||
The [Podman Compose definition](../deploy/docker-compose.yml) runs the app and a Tailscale sidecar for private access. The [systemd user unit](../deploy/podman-stack-bike-tinder.service) owns the running containers. Keep deployment-specific configuration outside Git and retain independent backups of the SQLite data. Do not expose the single-user app directly to the public internet.
|
||||
|
||||
Development lands on `dev`, verified changes move to `main`, and the running stack follows `release`. Build the candidate image before restarting the service. After cutover, check `/api/health` and confirm that the HTTP shell matches the intended revision. Keep the previous image for rollback.
|
||||
17
docs/HOW-IT-WORKS.md
Normal file
17
docs/HOW-IT-WORKS.md
Normal file
@@ -0,0 +1,17 @@
|
||||
# How Bike-Tinder works
|
||||
|
||||
## From classifieds to cards
|
||||
|
||||
The motorcycle-hunt crawler collects Kijiji listings in Nova Scotia and New Brunswick. The importer reads the crawler's snapshots, adds new listings, updates existing ones, and retires listings only after repeated misses. A blocked or failed fetch isn't proof that a listing is gone. See [Sources](SOURCES.md) and the [data model](DATA-MODEL.md).
|
||||
|
||||
The web app reads that catalog from SQLite and presents listings in a swipe deck or a searchable List. Your current verdict is editable; the app also records swipe events for ranking. Tap the sides of a deck card to browse its photos, the center to open the details, or the photo in the details view to open the fullscreen gallery. See the [interface spec](UI-SPEC.md) for gesture and keyboard behavior.
|
||||
|
||||
## Ranking and photos
|
||||
|
||||
With no swipe history, the deck starts with the motorcycle hunt's scoring rubric. Once there is history, the app builds a taste profile and uses it when ordering future batches. Batches can mix fresh bikes, wildcards, and second looks. A model runs outside the swipe path: the swipe itself never waits for a model response. See [Ranking](RANKING.md) and [Design](DESIGN.md).
|
||||
|
||||
The importer retains gallery URLs in source order. The running stack keeps primary photos locally; when a requested gallery photo isn't cached, the app redirects to the source image. A missing photo uses a placeholder. See [the gallery mirror backlog](BACKLOG.md#gallery-mirror-gap-found-2026-11-12-filing-for-a-later-phase).
|
||||
|
||||
## More detail
|
||||
|
||||
[Development and deployment](DEVELOPMENT.md) covers setup and testing. The [roadmap](PLAN.md) and [backlog](BACKLOG.md) cover planned work.
|
||||
@@ -20,6 +20,7 @@
|
||||
### Card geometry
|
||||
- `.card{position:absolute;left:14px;right:14px;top:6px;bottom:34px;border-radius:18px;overflow:hidden;background:var(--card);box-shadow:0 0 0 1px rgba(255,255,255,.07),0 18px 40px rgba(0,0,0,.5);will-change:transform;touch-action:none}`
|
||||
- Photo full-bleed (`object-fit:cover`); bottom gradient 52% tall (transparent → rgba(0,0,0,.55) @55% → .88). Info block at bottom:14px: chips row → title (23px/800, clamp 2 lines) → price (20px/600) → sub (13px, var(--mut)).
|
||||
- Photo fit is **contain** (v1.1): the whole photo is shown uncropped over a soft blurred backdrop of the same image (option C). The backdrop is decorative (blurred, dimmed, overflow-clipped); the sharp photo sits on top with a gentle shadow. The fullscreen viewer already fits; list thumbs stay `cover` (56px).
|
||||
- No photo → placeholder panel: 45° repeating stripes (#141419/#18181f), centered copy: "Photo pending — thumbnail backfill queued".
|
||||
- ⓘ button: 32px circle, top-right of card (rgba(0,0,0,.45), 1px rgba(255,255,255,.25) border) → opens the dossier for that card.
|
||||
- Chips: 11px/600, rgba(255,255,255,.14) bg, radius 999px. Production content: max 3 = seller chip ("Dealer" only when seller_type=dealer) + first 2 extras.
|
||||
@@ -51,6 +52,8 @@
|
||||
### Empty state
|
||||
Dashed panel, copy exactly: **"You're all caught up."** / "New bikes arrive nightly — next import 08:30." / "↺ brings the last card back." Undo restores the last card.
|
||||
|
||||
§2's quiet "You're all caught up." remains only for legacy (pre-section) mode. In section mode, when the deck can serve nothing at all — no fresh listings, no eligible second looks, no wildcards — the deck shows a prominent **"No more new bikes!"** panel with "New bikes arrive nightly — next import 08:30." and, when true, "↺ brings the last card back." This panel supersedes the report card in that state only; the report card remains the end-of-section screen whenever more cards can still be served (v1.1).
|
||||
|
||||
## 3. Dossier (fullscreen sheet) — one sheet, both doors
|
||||
|
||||
Opened from deck ⓘ (or tap) AND list row tap. iOS-sheet geometry: top gap 26px; `border-radius:18px 18px 0 0`; bg #0f0f13; slide-in `.3s cubic-bezier(.2,.8,.3,1)` from `translateY(103%)`. Backdrop: rgba(0,0,0,.38), z 69/70.
|
||||
@@ -87,7 +90,7 @@ Opened from deck ⓘ (or tap) AND list row tap. iOS-sheet geometry: top gap 26px
|
||||
|
||||
1. **Data wiring.** Deck buffer from `GET /api/deck` (limit 40, opaque cursor); refill when buffer <5 and a cursor exists. List from `GET /api/list`. Dossier from the row/card payload. Header from `GET /api/stats`.
|
||||
2. **Swipe persistence.** Commits fire `POST /api/swipe` optimistically — the UI never waits. Failures go to a retry queue (attempts at ~2s/5s/10s, then every 15s while the tab lives); toast "Couldn't save — retrying" on first failure. Undo fires `DELETE /api/swipe/{id}` through the same queue.
|
||||
3. **Badge.** `POST /api/badge/seen` once per session when the deck first renders. Header shows "{live} live" always; "· {new} new" only when new>0.
|
||||
3. **Badge.** `POST /api/badge/seen` once per session when the deck first renders. Header pill shows `{live} live · {fresh} fresh` always, and `· {new} new` only when new > 0. `fresh` = active listings with no swipe (the deck's new-pool predicate) — v1.1. The pill and the list sub-line refresh themselves shortly after any decision change (swipes, undo, dossier/list/matches edits) and whenever a new batch lands — no reload needed (v1.1.1, issue #2).
|
||||
4. **List filters + search** per §4 (mockup had placeholder chips only).
|
||||
5. **Matches real (§5); Trends stays stub.**
|
||||
6. **Images.** Every card/thumb references `/img/{id}` (server: cached file → 302 CDN → 404 → placeholder). The client never hotlinks directly.
|
||||
@@ -119,7 +122,7 @@ Human (parent-run after build): Glenn swipes a real deck from his phone and edit
|
||||
|
||||
- The deck serves ONE section at a time: 25 cards (default). A section is the unit of a swipe burst; when it is exhausted, the next one is forged (with an agent pass in between — §10.2).
|
||||
- Header right side, next to the stats: section progress "7/25" (12px/650, muted; turns `--accent1` at 25/25; fits within the existing header, no layout shift).
|
||||
- Section composition (engine side — RANKING.md): ≤5 SECOND LOOK cards + 2 WILDCARD cards + the remainder new.
|
||||
- Section composition (engine side — RANKING.md): every batch targets 25 cards = fresh first (up to 23 slots) + ≥2 SECOND LOOK cards whenever eligible stock exists + 2 WILDCARD cards; when fresh < 23, second looks fill the remainder up to 25. Re-nope returns stay ≤2 per batch; fresh shortfalls are never padded (v1.1).
|
||||
- ALL §2 mechanics apply unchanged inside a section: 5-deep stack, `.topcard` invariant, no-lock commit, stamps, undo; the buffer refills from the pinned section order.
|
||||
|
||||
### 10.2 Section report + forge
|
||||
@@ -133,13 +136,14 @@ Human (parent-run after build): Glenn swipes a real deck from his phone and edit
|
||||
- **Forge mode `ondemand` (default):** primary button **"Forge next 25"**. Tap → inline status "The agent is reading your strikes…" → new section hydrates. If the pass fails: "Agent offline — forging on the last read." and the forge still lands (fallback profile).
|
||||
- **Forge mode `strict`:** button disabled; caption "Waiting for the nightly read — next section after the agent runs."
|
||||
- Both modes: small toggle row under the actions — "Forge: on demand ⇄ strict" (persists `prefs['forge_mode']`).
|
||||
- When a forged batch reports `new: 0` the report shows: "Catalog fully reviewed — fresh listings arrive with the next 08:30 import; showing second looks." and the forge reads the same note in its status line (v1.1).
|
||||
- Undo from the report screen re-opens the section with the last card (§2 undo semantics).
|
||||
|
||||
### 10.3 Card bands (the ONLY card-face additions)
|
||||
|
||||
- Position: top-left inset (12px); `pointer-events:none`; no layout shift; no effect on stack metrics or drag. 11px/650, letter-spacing .4px, radius 999px, padding 4px 9px, max-width 78%; may wrap to 2 lines.
|
||||
- **WILDCARD — maybe you'll like this one instead** — color `#ffb43a`; bg `rgba(255,180,58,.14)`; border `1px solid rgba(255,180,58,.35)`.
|
||||
- **SECOND LOOK — you {liked|maybed|noped} this** — color `rgba(255,255,255,.85)`; bg `rgba(255,255,255,.10)`; border `1px solid rgba(255,255,255,.22)`.
|
||||
- **SECOND LOOK — you {liked|maybed|noped} this** — color `#c4b5fd`; bg `rgba(124,58,237,.22)`; border `1px solid rgba(167,139,250,.65)`; font-weight 800. Wildcard stays amber (`#ffb43a` family values unchanged) for contrast. The same band renders in the dossier ("info view") when the listing's slot is `return` or `wildcard` (v1.1).
|
||||
- No other text may sit on the card face in v3.
|
||||
|
||||
### 10.4 Tank gauge (match points, non-numeric)
|
||||
@@ -151,9 +155,10 @@ Human (parent-run after build): Glenn swipes a real deck from his phone and edit
|
||||
### 10.5 Dossier — "Why this rank"
|
||||
|
||||
- New block after chips, before "The machine":
|
||||
- Gauge + "{points}/100" (17px/700).
|
||||
- Gauge + "{points}%" (17px/700).
|
||||
- Up to 4 breakdown lines, strongest first, muted: "· {feature} {±n}"; agent contributions render as "· agent: {why} {±n}".
|
||||
- Footer: "from {N} strikes · read {relative}" (N = events count; time = profile version time).
|
||||
- Hidden-by-default detail: the breakdown lines and the "from N strikes" footer render only when `prefs['rubric_debug'] === 'on'` (default `'off'`). With the pref off the block shows **the tank gauge + "{points}%"** only — the minimal rubric display. The toggle lives in the Trends "Actions" area (why-breakdown on ⇄ off, same control style as the forge-mode toggle) — v1.1.
|
||||
- This is the only numeric display in the app (accepted — it exists for audit).
|
||||
|
||||
### 10.6 Trends tab (real)
|
||||
@@ -192,14 +197,15 @@ Top→bottom:
|
||||
|
||||
### 11.3 Fullscreen viewer
|
||||
|
||||
- Tap the CENTER third → fullscreen viewer opens on the photo currently shown.
|
||||
- Tap the photo in the dossier hero → fullscreen viewer opens (starts at photo 0). Direct card→viewer is retired (see §11.4); the viewer is reached from the dossier (v1.1).
|
||||
- Viewer: horizontal swipe = prev/next (clamp); pinch-zoom + double-tap = zoom (1×–~4×); segment bars stay visible; close via ✕ (36px, top-left) or pull-down (grabber or photo, `dy > 110` — the §3 idiom). Closing returns to the same card, same photo position; deck state untouched.
|
||||
- Also opens from the dossier hero (starts at photo 0). Same sheet geometry as the dossier (z-band 69/70), photo-first: no body, no actions row.
|
||||
- Viewer close (✕, pull-down, or Esc) returns to the dossier; the next Esc returns to the deck (v1.1).
|
||||
|
||||
### 11.4 Doors (supersedes the old tap→dossier)
|
||||
|
||||
- ⓘ (top-right of card) → dossier (unchanged). The card face now owns: **sides = flip, center = fullscreen**; the "tap anywhere → dossier" gesture is RETIRED.
|
||||
- The dossier stays reachable from ⓘ and from list rows (§3/§4 unchanged).
|
||||
- ⓘ (top-right of card) → dossier (unchanged). The card face now owns: **sides = flip, center = dossier (bike data first)**; the "tap anywhere → dossier" gesture is RETIRED and the B1 center-tap→fullscreen gesture is RETIRED in favour of it (v1.1).
|
||||
- Tapping the photo in the dossier hero opens the fullscreen image viewer (§11.3). Viewer close (✕, pull-down, or Esc) returns to the dossier; the next Esc returns to the deck. The dossier stays reachable from ⓘ and from list rows (§3/§4 unchanged).
|
||||
|
||||
### 11.5 Repeat rotation
|
||||
|
||||
|
||||
BIN
docs/images/bike-details.png
Normal file
BIN
docs/images/bike-details.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 74 KiB |
BIN
docs/images/swipe-deck.png
Normal file
BIN
docs/images/swipe-deck.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 101 KiB |
Reference in New Issue
Block a user