Lead with a short project overview and app screenshots

This commit is contained in:
Alexander Rozhenko
2026-11-18 00:40:21 -04:00
parent f4ebd33329
commit e1f06e3405
5 changed files with 70 additions and 136 deletions

42
docs/DEVELOPMENT.md Normal file
View 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
View 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.

Binary file not shown.

After

Width:  |  Height:  |  Size: 74 KiB

BIN
docs/images/swipe-deck.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 101 KiB