feat: initial project setup with roadmap, exercise data, and docs
Establish SneakySwole project foundation: - CLAUDE.md with project overview, stack, and development guidelines - 5-phase roadmap (scaffold, data layer, workout UI, logging, progression) - Exercise library YAML with 6 warmups and 20 exercises (form cues, tempo, sets) - User programs YAML with week 1/4 targets for Phillip and Daughter - Design doc capturing roadmap, data, and auth model decisions - Code guidelines, security standards, and .gitignore - Source workout spreadsheet (workout_plan_v2.xlsx) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
119
CLAUDE.md
Normal file
119
CLAUDE.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# 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 `<html>`
|
||||
- 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
|
||||
<!-- Claude can track TODOs, known issues, technical debt, or areas needing attention -->
|
||||
|
||||
### Session History
|
||||
<!-- Claude can maintain a log of significant changes or milestones -->
|
||||
- **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
|
||||
<!-- Current work, blockers, reminders -->
|
||||
- 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
|
||||
<!-- Significant updates, refactors, or milestones -->
|
||||
- **2026-02-23** — Initial CLAUDE.md created. Project overview, stack, and structure defined.
|
||||
Reference in New Issue
Block a user