# CLAUDE.md ## Project Overview **Purpose:** SneakySwole — an open-source workout tracking and programming app **Technologies:** Python, FastAPI, SQLite3, HTMX, Pico CSS (dark theme), Docker **Description:** A lightweight, open-source workout platform built with FastAPI on the backend, HTMX for dynamic frontend interactions (no heavy JS framework), SQLite3 for local/embedded data storage, and a dark-themed UI lightly based on Pico CSS. Fully containerized via Docker for easy self-hosting. Designed to be self-hostable, simple to contribute to, and easy to extend. **GitHub handle:** sneakygeek (not sneakyllc) --- ## Development Guidelines ### Project Structure I prefer to have my source in `app`, not `src`. I prefer **centralizing common logic** such as HTTP wrappers, logging handlers, validators, etc. I like keeping things **modular**, with: * `/app/services/...` — business logic, workout plans, progression calculations * `/app/utils/...` — shared helpers, formatters, validators * `/app/models/...` — SQLite/SQLModel schema definitions * `/app/routes/...` — FastAPI route handlers (one file per domain) * `/app/templates/...` — Jinja2 HTML templates (HTMX-friendly, partial-first) * `/app/static/...` — CSS overrides, minimal JS, any static assets * `Dockerfile` — container image definition * `docker-compose.yaml` — primary way to run the app locally and in production * `data/` — SQLite DB lives here (gitignored, persisted via Docker volume) * Typed config loaders * YAML-driven config structures ### Tech Stack Specifics #### Backend - **FastAPI** — all API and page routes - **SQLite3** via the standard library or **SQLModel** for ORM if needed - Keep DB access in `/app/services/` — never query the DB directly from routes - Use **Alembic** for migrations even with SQLite (keeps things portable) #### Frontend - **HTMX** for all dynamic interactions — avoid writing vanilla JS unless absolutely necessary - Prefer `hx-get` / `hx-post` with **partial HTML responses** (template fragments), not JSON - **Pico CSS** as the base — dark theme via `data-theme="dark"` on `` - Custom overrides in `/app/static/css/sneakyswole.css` — keep Pico mostly untouched - Templates use **Jinja2** (built into FastAPI via `Jinja2Templates`) - Design should feel clean and gym-appropriate — dark, bold, minimal #### Database - **SQLite3** — single file DB, ideal for self-hosted / local use - DB file lives at `data/sneakyswole.db` (excluded from git, gitignored) - Schema covers: users, exercises, workouts, workout_days, sets, progress_log - Seed data for default exercise library (from the spreadsheet program) #### Docker - Project is fully containerized — `Dockerfile` at the project root - **`docker-compose.yaml`** at the project root is the primary way to run the app - The `data/` directory (SQLite DB) is mounted as a **named volume** so data persists across container restarts - Static files and templates are baked into the image — no bind mounts needed in production - `.env` file is used for environment config (never committed); `docker-compose.yaml` references it via `env_file` - Typical compose setup: single `app` service, port `8000` exposed, volume for `data/` - Keep the image lean — use a slim Python base image (e.g. `python:3.12-slim`) ### Coding Standards I often follow a pattern **brainstorm → design → code → revise** and like that flow. Reference `docs/code_guidelines.md` for code standards and rules. ### Security Standards Reference `docs/security.md` for security guidance and standards. --- ## ⚠️ CLAUDE WORKSPACE BELOW ⚠️ **The sections above define my development preferences and standards.** **Everything below this line is working context for Claude to track project-specific information, decisions, and progress.** --- ## Claude Context & Project Notes ### Project Context - Open-source project under the **sneakygeek** GitHub account - Workout program based on a 4-day split: Push / Pull / Lower / Full Body - Two user profiles initially: Phillip (260 lbs, 6'0", bulging disc) and Daughter (140 lbs, 5'8") - Equipment: 2x adjustable dumbbells up to 55 lbs each + bodyweight - Progression model: +1-2 reps/week, +5 lbs every 2 weeks, deload at week 5 - Warmup is standardized (Cat/Cow, Fire Hydrant, Thoracic Rotation/Extension, etc.) - Each exercise has full form cues stored in the DB - The spreadsheet (`workout_plan_v2.xlsx`) is the source of truth for the initial exercise seed data ### Core Features (Planned) - [ ] User profiles with stats (weight, height, equipment) - [ ] Workout day viewer (warmup + main workout) - [ ] Per-exercise logging (sets, reps, weight, felt easy?) - [ ] Auto-progression suggestions based on log history - [ ] Exercise library with full form cues - [ ] 4-week schedule view - [ ] Progress log with history - [ ] Dark UI, mobile-friendly ### Implementation Notes ### Session History - **2026-02-23** — Project named SneakySwole. Stack finalized: FastAPI + SQLite3 + HTMX + Pico CSS dark theme + Docker (docker-compose.yaml). Workout program designed (4-day split, warmup routine, progressive overload model). Spreadsheet v2 completed with full form cues for all exercises. ### Active Tasks & Notes - Set up initial FastAPI project scaffold - Write `Dockerfile` and `docker-compose.yaml` - Design SQLite schema based on workout spreadsheet structure - Build Jinja2 base template with Pico dark theme - Seed exercise library from spreadsheet data ### Change Log - **2026-02-23** — Initial CLAUDE.md created. Project overview, stack, and structure defined.