feat: Add project foundation, documentation, and Docker setup
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Jan Novak
186
plans/001-initial-implementation-plan.md
Normal file
186
plans/001-initial-implementation-plan.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# Training Tracker - Implementation Plan
|
||||
|
||||
## Project Overview
|
||||
A mobile-friendly web application for tracking training activities with a Golang backend and SQL/NoSQL database.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Project Foundation
|
||||
|
||||
### 1.1 Project Structure
|
||||
```
|
||||
training-tracker/
|
||||
├── backend/
|
||||
│ ├── cmd/
|
||||
│ │ └── server/
|
||||
│ │ └── main.go
|
||||
│ ├── internal/
|
||||
│ │ ├── api/ # HTTP handlers
|
||||
│ │ ├── models/ # Data structures
|
||||
│ │ ├── storage/ # Database layer
|
||||
│ │ └── service/ # Business logic
|
||||
│ ├── go.mod
|
||||
│ └── go.sum
|
||||
├── frontend/
|
||||
│ ├── index.html
|
||||
│ ├── css/
|
||||
│ │ └── styles.css
|
||||
│ ├── js/
|
||||
│ │ ├── app.js
|
||||
│ │ ├── api.js
|
||||
│ │ └── components/
|
||||
│ └── assets/
|
||||
├── docker-compose.yml
|
||||
└── readme.md
|
||||
```
|
||||
|
||||
### 1.2 Database Schema Design
|
||||
**Core entities:**
|
||||
- **users** - User accounts (id, username, email, password_hash, created_at)
|
||||
- **exercises** - Exercise definitions (id, name, type, muscle_group, description)
|
||||
- **training_plans** - Training plan templates (id, user_id, name, description)
|
||||
- **plan_exercises** - Exercises in a plan (id, plan_id, exercise_id, sets, reps, duration, order)
|
||||
- **sessions** - Completed training sessions (id, user_id, plan_id, date, notes)
|
||||
- **session_entries** - Individual exercise entries (id, session_id, exercise_id, weight, reps, duration, sets_completed)
|
||||
|
||||
**Choice:** PostgreSQL (can use Docker for local development)
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Backend Development (Golang)
|
||||
|
||||
### 2.1 Initial Setup
|
||||
- Initialize Go module
|
||||
- Set up HTTP router (standard library `net/http` or `chi`/`gorilla/mux`)
|
||||
- Configure environment variables
|
||||
- Set up database connection
|
||||
|
||||
### 2.2 API Endpoints
|
||||
```
|
||||
# Auth endpoints (deferred to v2)
|
||||
# POST /api/auth/register
|
||||
# POST /api/auth/login
|
||||
|
||||
Exercises:
|
||||
GET /api/exercises # List all exercises
|
||||
POST /api/exercises # Create exercise
|
||||
GET /api/exercises/:id # Get exercise
|
||||
PUT /api/exercises/:id # Update exercise
|
||||
DELETE /api/exercises/:id # Delete exercise
|
||||
|
||||
Training Plans:
|
||||
GET /api/plans # List user's plans
|
||||
POST /api/plans # Create plan
|
||||
GET /api/plans/:id # Get plan with exercises
|
||||
PUT /api/plans/:id # Update plan
|
||||
DELETE /api/plans/:id # Delete plan
|
||||
|
||||
Sessions:
|
||||
GET /api/sessions # List sessions (with filters)
|
||||
POST /api/sessions # Create/start session
|
||||
GET /api/sessions/:id # Get session details
|
||||
PUT /api/sessions/:id # Update session
|
||||
DELETE /api/sessions/:id # Delete session
|
||||
POST /api/sessions/:id/entries # Add entry to session
|
||||
```
|
||||
|
||||
### 2.3 Core Backend Tasks
|
||||
1. Set up Go project structure and dependencies
|
||||
2. Set up PostgreSQL via Docker
|
||||
3. Implement database migrations
|
||||
4. Create data models and repository layer
|
||||
5. Implement REST API handlers
|
||||
6. Add input validation and error handling
|
||||
7. Implement CORS for frontend communication
|
||||
8. (v2) Add authentication
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Frontend Development (HTML/CSS/JS)
|
||||
|
||||
### 3.1 Mobile-First Design
|
||||
- Responsive CSS with mobile breakpoints
|
||||
- Touch-friendly UI elements
|
||||
- Offline-capable design (future PWA)
|
||||
|
||||
### 3.2 Core Views/Pages
|
||||
1. **Dashboard** - Overview of recent sessions, quick actions
|
||||
2. **Training Plan View** - Display exercises for current session
|
||||
3. **Session Logger** - Form to enter weights/reps/duration during workout
|
||||
- Strength: weight, sets, reps
|
||||
- Cardio: duration, distance, heart rate (optional)
|
||||
4. **History** - View past sessions and progress
|
||||
5. **Exercise Library** - Browse and manage exercises
|
||||
6. (v2) **Login/Register** - Authentication screens
|
||||
|
||||
### 3.3 Frontend Tasks
|
||||
1. Create base HTML structure and navigation
|
||||
2. Implement responsive CSS (flexbox/grid)
|
||||
3. Build API client module (fetch wrapper)
|
||||
4. Create reusable UI components
|
||||
5. Implement session logging interface
|
||||
6. Add form validation
|
||||
7. Implement local storage for offline data entry
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Integration & Testing
|
||||
|
||||
### 4.1 Integration
|
||||
- Connect frontend to backend API
|
||||
- Test all CRUD operations
|
||||
- Handle loading states and errors
|
||||
- Implement authentication flow
|
||||
|
||||
### 4.2 Testing
|
||||
- Backend: Unit tests for handlers and services
|
||||
- Frontend: Manual testing on mobile devices
|
||||
- API: Integration tests
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Deployment (Optional for v1)
|
||||
|
||||
- Docker containerization
|
||||
- Docker Compose for local development
|
||||
- Basic deployment documentation
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements (v2+)
|
||||
- Strava integration
|
||||
- Whoop integration
|
||||
- Progress charts and analytics
|
||||
- Workout timer
|
||||
- PWA with offline support
|
||||
- Export data (CSV/PDF)
|
||||
|
||||
---
|
||||
|
||||
## Recommended Implementation Order
|
||||
|
||||
1. **Backend foundation** - Go project setup, PostgreSQL via Docker, basic models
|
||||
2. **Core API** - Exercises and sessions endpoints (strength + cardio support)
|
||||
3. **Frontend skeleton** - HTML structure, CSS, navigation
|
||||
4. **Session logging** - The core feature (enter workout data)
|
||||
5. **Training plans** - Plan viewing and management
|
||||
6. **Polish** - Error handling, validation, UX improvements
|
||||
7. (v2) **Authentication** - User accounts
|
||||
|
||||
---
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **Database**: PostgreSQL (via Docker for local dev)
|
||||
- **Authentication**: None initially (single-user mode), add in v2
|
||||
- **Exercise types**: Both strength (weight/sets/reps) and cardio (duration/distance/HR)
|
||||
|
||||
## Verification
|
||||
|
||||
After implementation, verify by:
|
||||
1. Start PostgreSQL container and backend server
|
||||
2. Open frontend in browser (mobile viewport)
|
||||
3. Create a test exercise (e.g., "Bench Press" - strength type)
|
||||
4. Create a training plan with exercises
|
||||
5. Log a session with actual data entry
|
||||
6. View session history
|
||||
152
plans/testing-plan.md
Normal file
152
plans/testing-plan.md
Normal file
@@ -0,0 +1,152 @@
|
||||
# Backend Testing Plan
|
||||
|
||||
## Overview
|
||||
|
||||
Add comprehensive tests for the training-tracker backend following Go best practices and the CLAUDE.md guidelines (table-driven tests).
|
||||
|
||||
**Scope:** Both unit tests (handlers with mocks) AND integration tests (repositories with testcontainers)
|
||||
|
||||
**Plan storage:** Copy this plan to `training-tracker/plans/testing-plan.md`
|
||||
|
||||
## Current State
|
||||
|
||||
- **No existing tests** - greenfield testing
|
||||
- 3 packages to test: `api`, `storage`, `models`
|
||||
- Dependencies: handlers → repositories → database
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### 1. Unit Tests for API Handlers
|
||||
|
||||
Test HTTP handlers with mocked repositories.
|
||||
|
||||
**Files to create:**
|
||||
- `internal/api/exercises_test.go`
|
||||
- `internal/api/plans_test.go`
|
||||
- `internal/api/sessions_test.go`
|
||||
|
||||
**Approach:**
|
||||
- Define repository interfaces
|
||||
- Create mock implementations
|
||||
- Use `httptest.NewRecorder()` and `httptest.NewRequest()`
|
||||
- Table-driven tests for each endpoint
|
||||
|
||||
**Test cases per handler:**
|
||||
- List: empty result, multiple results
|
||||
- GetByID: found, not found
|
||||
- Create: valid input, missing required fields, invalid type
|
||||
- Update: found, not found, validation errors
|
||||
- Delete: found, not found
|
||||
|
||||
### 2. Integration Tests for Storage Layer
|
||||
|
||||
Test repositories against real PostgreSQL using testcontainers.
|
||||
|
||||
**Files to create:**
|
||||
- `internal/storage/exercises_test.go`
|
||||
- `internal/storage/plans_test.go`
|
||||
- `internal/storage/sessions_test.go`
|
||||
- `internal/storage/db_test.go`
|
||||
|
||||
**Approach:**
|
||||
- Use `testcontainers-go` to spin up PostgreSQL
|
||||
- Run migrations before tests
|
||||
- Test CRUD operations end-to-end
|
||||
- Test transaction rollback scenarios
|
||||
|
||||
**Test cases:**
|
||||
- CRUD operations for each entity
|
||||
- Cascading deletes
|
||||
- Transaction handling in plans (create/update)
|
||||
- NULL field handling
|
||||
- Foreign key constraints
|
||||
|
||||
### 3. Test File Structure
|
||||
|
||||
```
|
||||
backend/internal/
|
||||
├── api/
|
||||
│ ├── exercises_test.go
|
||||
│ ├── plans_test.go
|
||||
│ ├── sessions_test.go
|
||||
│ └── mocks_test.go # Shared mock implementations
|
||||
├── storage/
|
||||
│ ├── testhelpers_test.go # Shared test database setup
|
||||
│ ├── exercises_test.go
|
||||
│ ├── plans_test.go
|
||||
│ └── sessions_test.go
|
||||
└── models/
|
||||
└── (no tests needed - pure data structures)
|
||||
```
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Create plans folder** and store this plan:
|
||||
- Create `training-tracker/plans/`
|
||||
- Copy this plan to `training-tracker/plans/testing-plan.md`
|
||||
|
||||
2. **Add test dependencies** to go.mod:
|
||||
- `github.com/testcontainers/testcontainers-go`
|
||||
- Use standard library for assertions (no testify)
|
||||
|
||||
3. **Create repository interfaces** in `internal/api/`:
|
||||
- `ExerciseRepository` interface
|
||||
- `PlanRepository` interface
|
||||
- `SessionRepository` interface
|
||||
|
||||
4. **Create mock implementations** for unit testing handlers
|
||||
|
||||
5. **Create test helpers** for integration tests:
|
||||
- Shared PostgreSQL container setup
|
||||
- Database cleanup between tests
|
||||
|
||||
6. **Write handler unit tests** (table-driven):
|
||||
- All CRUD operations
|
||||
- Validation error paths
|
||||
- Not found scenarios
|
||||
|
||||
7. **Write storage integration tests** (table-driven):
|
||||
- All repository methods
|
||||
- Edge cases and error conditions
|
||||
|
||||
8. **Update CLAUDE.md** with testing instructions
|
||||
|
||||
## Files to Modify
|
||||
|
||||
- `backend/go.mod` - add test dependencies
|
||||
- `backend/internal/api/router.go` - extract interfaces for testability
|
||||
- `backend/CLAUDE.md` - add testing instructions
|
||||
|
||||
## Files to Create
|
||||
|
||||
- `plans/testing-plan.md` - this plan document
|
||||
- `backend/internal/api/interfaces.go` - repository interfaces
|
||||
- `backend/internal/api/mocks_test.go` - mock implementations
|
||||
- `backend/internal/api/exercises_test.go`
|
||||
- `backend/internal/api/plans_test.go`
|
||||
- `backend/internal/api/sessions_test.go`
|
||||
- `backend/internal/storage/testhelpers_test.go`
|
||||
- `backend/internal/storage/exercises_test.go`
|
||||
- `backend/internal/storage/plans_test.go`
|
||||
- `backend/internal/storage/sessions_test.go`
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Run all tests
|
||||
go test ./...
|
||||
|
||||
# Run with verbose output
|
||||
go test -v ./...
|
||||
|
||||
# Run with coverage
|
||||
go test -cover ./...
|
||||
|
||||
# Run only unit tests (fast)
|
||||
go test -short ./...
|
||||
|
||||
# Run specific package
|
||||
go test -v ./internal/api/...
|
||||
```
|
||||
Reference in New Issue
Block a user