How oluwatooki/workout-tracker works
Purpose and Runtime
Workout Tracker is a FastAPI REST API for user accounts, exercise lookup, workout-plan lifecycle, scheduling, workout logging, and progress reports. It runs locally via app/run.py, with application composition in app/main.py; FastAPI serves interactive OpenAPI documentation at /docs.
API Composition
Route modules separate the public resource domains and are expected to be registered by the application bootstrap:
• Identity: app/endpoints/users.py, app/endpoints/login.py
• Plans and scheduling: app/endpoints/workout.py, app/endpoints/scheduled_workouts.py
• Exercise catalog, logs, and reporting: app/endpoints/exercises.py, app/endpoints/workout_logs.py, app/endpoints/reports.py
Requests enter endpoint handlers, are validated into schemas, authorized where needed, then persist or query domain records.
Identity and Security Boundary
Registration, login, and current-user access establish the authenticated-user boundary. Login returns JWTs; protected plan, schedule, log, and report operations are scoped to the current user. JWT/security behavior is centralized in app/core/security.py, with account-facing routes in app/endpoints/login.py and app/endpoints/users.py.
Workout Domain Flow
Users create and manage workout plans, then schedule planned workouts and record completed sessions. Logged sessions become the historical input to progress reporting. The main lifecycle boundaries are represented by:
• Plans: app/endpoints/workout.py, app/schemas/workout_schemas.py
• Scheduled instances: app/endpoints/scheduled_workouts.py, app/schemas/scheduled_workouts_schemas.py
• Completed logs: app/endpoints/workout_logs.py, app/schemas/logs_schemas.py
Data Model and Persistence
PostgreSQL is the material persistence dependency. Schema creation is explicit in app/db/scripts/create_schema.sql; application database access is centralized through app/db/connection.py. Exercise catalog data can be provisioned through app/db/seeds/seed_exercises.py. Database details and JWT/database environment values are supplied through .env based on app/.env.example.
Validation and Reporting
Pydantic-style request/response contracts isolate API inputs from database operations, especially for users, exercises, plans, schedules, and logs: app/schemas/users_schemas.py, app/schemas/exercises_schemas.py, app/schemas/workout_schemas.py. Reporting reads prior workout/log data to expose progress through app/endpoints/reports.py; it is a query/aggregation boundary rather than a separate service.
Cross-Cutting Core Services
Configuration is centralized in app/core/config.py; security and authentication utilities reside in app/core/security.py. Documentation/examples support the FastAPI API surface through app/core/docs.py and app/core/examples.py. No frontend, queue, cache, or external SaaS integration is indicated; the architecture is a single Python API process backed by PostgreSQL.
Main entry points: main.py FastAPI application · connection.py Database access · security.py JWT security · workout.py Workout plans
Components 19
Runtime
- Local runner · Starts the API locally.
app/run.py - FastAPI application · Composes and registers the REST API.
app/main.py
API domains
- Identity routes · Registration and current-user account access.
app/endpoints/users.py - Login routes · Authenticates users and returns JWTs.
app/endpoints/login.py - Workout plans · Creates and manages user workout plans.
app/endpoints/workout.py - Scheduled workouts · Manages planned workout instances.
app/endpoints/scheduled_workouts.py - Workout logs · Records completed workout sessions.
app/endpoints/workout_logs.py - Progress reports · Aggregates prior workout history.
app/endpoints/reports.py - Exercise catalog
app/endpoints/exercises.py
Core services
- JWT security · Establishes the protected current-user boundary.
app/core/security.py - Configuration · Loads database and JWT environment values.
app/core/config.py - API documentation · Supports the FastAPI documentation surface.
app/core/docs.py
Data & contracts
- Plan contracts
app/schemas/workout_schemas.py - Schedule contracts
app/schemas/scheduled_workouts_schemas.py - Log contracts
app/schemas/logs_schemas.py - Database access · Centralized application access to PostgreSQL.
app/db/connection.py - PostgreSQL · Stores accounts, catalog, plans, schedules, and logs.
- Database schema · Explicit database schema creation.
app/db/scripts/create_schema.sql - Exercise seed · Provisions exercise catalog data.
app/db/seeds/seed_exercises.py
Connections 30
- Local runner → FastAPI application: starts
- FastAPI application → Identity routes: registers
- FastAPI application → Login routes: registers
- FastAPI application → Workout plans: registers
- FastAPI application → Scheduled workouts: registers
- FastAPI application → Workout logs: registers
- FastAPI application → Progress reports: registers
- FastAPI application → Exercise catalog: registers
- FastAPI application → API documentation: serves /docs
- Login routes → JWT security: issues JWTs
- Identity routes → JWT security: current user
- Workout plans → JWT security: authorizes
- Scheduled workouts → JWT security: authorizes
- Workout logs → JWT security: authorizes
- Progress reports → JWT security: scopes queries
- Workout plans → Plan contracts: validates
- Scheduled workouts → Schedule contracts: validates
- Workout logs → Log contracts: validates
- Workout plans → Database access: persists plans
- Scheduled workouts → Database access: persists schedules
- Workout logs → Database access: persists sessions
- Progress reports → Database access: reads history
- Exercise catalog → Database access: queries catalog
- Identity routes → Database access: persists accounts
- Database access → Configuration: loads settings
- Database access → PostgreSQL: connects
- Database schema → PostgreSQL: creates tables
- Exercise seed → PostgreSQL: loads catalog
- Workout plans → Scheduled workouts: plans are scheduled as
- Workout logs → Progress reports: historical input