Lead with a short project overview and app screenshots
This commit is contained in:
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.
|
||||
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