# Design: Roadmap, Exercise Data, and Auth Model

**Date:** 2026-02-23
**Status:** Approved

## Overview

This document captures the design decisions for the SneakySwole roadmap structure, exercise data management, and authentication model.

## Roadmap Structure

Five phases, each producing a testable milestone:

1. **Scaffold & Infrastructure** — project structure, Docker, base template, logging
2. **Data Layer & Seeding** — SQLite schema, Alembic migrations, YAML-based exercise/program seeding
3. **Workout UI** — admin auth, profile management, workout viewer, exercise browser
4. **Logging & Tracking** — per-exercise logging, session tracking, log history
5. **Progression & Analytics** — auto-progression, schedule view, progress dashboard

Full details in `docs/roadmap.md`.

## Exercise Data Design

### Separated YAML Files

Exercise data is split into two config files for clean separation of concerns:

- **`config/exercises.yaml`** — Universal exercise library
  - Exercise name, muscle group, workout day, sets, tempo, form cues
  - Warmup exercises (name, type, reps/time, form cues)
  - Rarely changes; defines the available exercise catalog

- **`config/user_programs.yaml`** — Per-user programming
  - References exercises by name
  - Week 1 and week 4 reps and weights per user per exercise
  - Changes when users adjust their programming or new users are added

### Seeding Flow

1. On first run (empty DB), the seed script reads both YAML files
2. Exercises and warmups are inserted into their respective tables
3. User profiles are created (admin from `.env`, others from user_programs.yaml)
4. User-specific programming (reps/weights) is linked to exercises and users
5. Subsequent runs skip seeding if data already exists

### Why YAML Over Spreadsheet

- Human-readable and version-controllable
- Easy to update without special tools
- Can be validated with schema checks
- Spreadsheet remains source of truth for initial data extraction only

## Authentication Model

### Phase 1: Simple Admin Auth

- Single admin user with credentials stored in `.env` (`ADMIN_USERNAME`, `ADMIN_PASSWORD`)
- On first run, admin user is created in DB with bcrypt-hashed password
- Admin logs in via a simple login form (session-based auth)
- Admin creates user profiles through the UI (no login for profiles)
- Profile switcher in navigation allows admin to select the active profile
- All workout logging happens under the selected profile

### Security Considerations

- Passwords hashed with bcrypt (never stored plaintext)
- `.env` file is gitignored and never committed
- `.env.example` documents required variables without real values
- Session tokens with reasonable expiry
- Admin-only routes protected by auth middleware

### Future Upgrade Path

- Phase 1 auth is designed to be replaceable
- If multi-user login is needed later, add login credentials to the user profiles table
- Profile switcher becomes unnecessary when each user logs in independently