worth-the-run

●live active none private

README

# Worth the Run

Worth the Run is a small FastAPI app for rating audiobooks by what actually matters on a run: content, narrator performance, run fit, and the overall chance that the book improves your miles instead of becoming homework with chapters.

## Stack

- Python
- FastAPI
- Jinja2 templates
- Tailwind CSS via CDN
- SQLite
- Local CSV seed data

## Local Setup

```bash
pip install -r requirements.txt
python main.py
```

Open [http://localhost:8006](http://localhost:8006).

On first startup the app creates `worth_the_run.db` and seeds it from `seed_audiobooks.csv`.

## Render Deployment

Render's [FastAPI deployment docs](https://render.com/docs/deploy-fastapi) use these commands:

- Build command: `pip install -r requirements.txt`
- Start command: `uvicorn main:app --host 0.0.0.0 --port $PORT`

This repo also includes a `Procfile` with the same start command.

SQLite is fine for v1 and local use. On Render, the database file lives on the service filesystem. For durable production use, add a Render disk or move ratings to a managed database.

## GitHub Flow

```bash
git init
git add .
git commit -m "Build Worth the Run FastAPI app"
git branch -M main
git remote add origin <your-github-repo-url>
git push -u origin main
```

Then create a Render Web Service from that GitHub repo.

## App Pages

- `/` Dashboard with current listening, want list, recommendations, and recently finished
- `/rate` Fast rating cards
- `/recommendations` transparent recommendation scores and verdicts
- `/profile` taste summary based on ratings
- `/audiobooks/{id}` audiobook detail and explanation

## Recommender

`recommender.py` uses transparent scoring rather than ML. Ratings build preference weights for categories and trait scores. Narrator and run-fit ratings carry extra weight. Dense books are penalized for running when the user's ratings show that density hurts run enjoyment.

STATUS

No STATUS.

DECISIONS

No DECISIONS.

MEMORY

No MEMORY.

CLAUDE.md

No CLAUDE.md.

Diary mentions

No recent diary mentions for this app.

Render