Files

Phillip Tarrant 3f7ce965e1 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>

2026-02-23 21:55:31 -06:00

5.8 KiB

Raw Blame History

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

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.

5.8 KiB Raw Blame History