# Doris Barbell V1 Implementation Plan

> For Hermes: use subagent-driven-development if this gets split into parallel implementation chunks later.

Goal: ship a private-first exercise tracking site on PD that lets John log structured workouts, reps, weight, body weight, BMI, and related body metrics, while leaving a clean path for Manndra as a second household user later.

Architecture: start with the proven Doris pattern already used elsewhere in the homelab: a small FastAPI + Jinja app with a JSON-backed store for fast delivery, then graduate the storage layer to SQLite or shared Postgres if the workflow proves sticky. Keep the initial data model structured enough that templates, charts, PR tracking, and multi-user auth can layer in without a rewrite.

Tech stack: FastAPI, Jinja2, JSON state store for V1 bootstrap, Docker Compose on PD, responsive CSS, pytest.

---

## Working assumptions locked in for now

- Audience: John now, Manndra stubbed for later.
- Hosting: PD.
- Device target: both phone and desktop, mobile-friendly first.
- Access model default: private-first now, public route optional later.
- Backend default: Python / FastAPI because it matches the existing Doris app pattern and is fastest to ship here.
- Reporting default: build toward workout history, PR/1RM, and body-metric trends, but do not block V1 logging on all charts being perfect.
- Measurement preference: imperial only.
- Progress photos: out for V1.
- Muscle-size tracking: not a priority.
- Current height assumption for seed data: 68.5 inches unless John corrects it.
- Exercise catalog: John's current five-day split has now been imported as the default exercise/routine library with a default prescription of 3 sets x 10 reps; working weights are still pending.

## Current scaffold already started

- New repo source: `home/doris-barbell`
- Initial FastAPI app skeleton exists.
- JSON state seeds `john` plus stub `manndra`.
- Implemented endpoints:
  - `GET /api/health`
  - `GET /api/dashboard/summary`
  - `PUT /api/profile/{user_id}`
  - `POST /api/profile/{user_id}/weight`
  - `GET /api/history/{user_id}/weights`
  - `POST /api/profile/{user_id}/measurements`
  - `GET /api/history/{user_id}/measurements`
  - `POST /api/exercises/templates`
  - `GET /api/exercises/templates`
  - `POST /api/routines`
  - `GET /api/routines`
  - `POST /api/workouts`
  - `GET /api/history/{user_id}/workouts`
  - `GET /api/progression/{user_id}/exercises`
- Homepage now renders current metrics, recent workouts, exercise bests, and placeholder template/routine scaffolding.
- Homepage now renders John's imported five-day split as the default routine board.
- Homepage now includes mobile-friendly HTML forms for quick weight entry, body measurements, exercise templates, routine drafts, and quick workout logging.
- Homepage now includes John-focused recent history snapshots so the app is useful before charts exist.
- Tests currently cover health, seeded users, BMI calculation, imperial measurement logging, exercise template creation, routine creation, history ordering, structured workout logging, progression summaries, homepage render, and form-post redirects.

## Next build slices

### Slice 1: stabilize the base data model
1. Add lightweight migration/version handling inside the JSON state.
2. Add validation rules around timestamps, duplicate entries, and bad user IDs.
3. Add additional non-muscle health/body metrics only if John actually wants them surfaced.
4. Keep every write user-scoped so Manndra can be added later without rework.

### Slice 2: make workout logging genuinely usable
1. Add exercise template edit/delete.
2. Add routine edit/delete and clone-from-template flow.
3. Add support for warm-up vs working sets.
4. Add notes per exercise and per set.
5. Add estimated 1RM helpers for barbell lifts.

### Slice 3: give John the actual dashboards he will care about
1. Current weight card and trend sparkline.
2. BMI and body-fat trend history.
3. Recent workouts table.
4. Exercise-specific progression view.
5. PR cards and recent milestone callouts.
6. Body-measurement history cards for waist, hips, chest, and neck.
7. UI screens that consume the new history endpoints.

### Slice 4: prepare for shared household use without forcing it now
1. Add auth choice once John settles on private-only vs public exposure.
2. Preserve seeded Manndra user but hide stub-only clutter in the UI.
3. Keep imperial defaults while leaving room for future per-user units if needed.

### Slice 5: deploy on PD cleanly
1. Add `.env` from `.env.example` in the live deploy path.
2. Validate with `docker compose --env-file .env config`.
3. Deploy under `/mnt/docker-ssd/docker/compose/doris-barbell`.
4. Decide whether it stays LAN-only or gets a routed hostname.

## Biggest open product questions still waiting on John

1. Working weights for the imported split.
2. Preferred auth mode for V1.
3. Which extra non-photo metrics matter beyond weight, BMI, body fat, waist, hips, chest, and neck.
4. Whether 68.5 inches should be treated as the current real height, or whether he wants 69 inches used instead.
5. Whether he wants one-step quick workout entry or a fuller workout-builder flow first.

## Verification commands

```bash
cd /home/fizzlepoof/repos/truenas-stacks/home/doris-barbell
. .venv/bin/activate
pytest tests/test_app.py -q
python3 -m py_compile app/main.py app/config.py app/models.py app/routes/api.py app/routes/ui.py app/services/store.py
python3 - <<'PY'
import yaml
from pathlib import Path
print(yaml.safe_load(Path('docker-compose.yaml').read_text())['services'].keys())
PY
```
