# oluwatooki/workout-tracker architecture

> Architecture diagram of the GitHub repository oluwatooki/workout-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oluwatooki/workout-tracker
- Repository: https://github.com/oluwatooki/workout-tracker

## Overview

#### 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: [`app/main.py`](https://github.com/oluwatooki/workout-tracker/blob/main/app/main.py) (FastAPI application), [`app/db/connection.py`](https://github.com/oluwatooki/workout-tracker/blob/main/app/db/connection.py) (Database access), [`app/core/security.py`](https://github.com/oluwatooki/workout-tracker/blob/main/app/core/security.py) (JWT security), [`app/endpoints/workout.py`](https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/workout.py) (Workout plans)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_runner["Local runner<br/>Python entrypoint<br/>[run.py]"]
  node_app{{"FastAPI application<br/>application bootstrap<br/>[main.py]"}}
end

subgraph group_api["API domains"]
  node_identity["Identity routes<br/>route handlers<br/>[users.py]"]
  node_login["Login routes<br/>route handlers<br/>[login.py]"]
  node_plans["Workout plans<br/>route handlers<br/>[workout.py]"]
  node_schedules["Scheduled workouts<br/>route handlers"]
  node_logs["Workout logs<br/>route handlers<br/>[workout_logs.py]"]
  node_reports["Progress reports<br/>query routes<br/>[reports.py]"]
  node_exercises["Exercise catalog<br/>route handlers<br/>[exercises.py]"]
end

subgraph group_core["Core services"]
  node_security{{"JWT security<br/>authentication service<br/>[security.py]"}}
  node_config["Configuration<br/>settings<br/>[config.py]"]
  node_api_docs["API documentation<br/>documentation support<br/>[docs.py]"]
end

subgraph group_data["Data &amp; contracts"]
  node_plan_contracts["Plan contracts<br/>Pydantic schemas<br/>[workout_schemas.py]"]
  node_schedule_contracts["Schedule contracts<br/>Pydantic schemas"]
  node_log_contracts["Log contracts<br/>Pydantic schemas<br/>[logs_schemas.py]"]
  node_db_connection["Database access<br/>connection layer<br/>[connection.py]"]
  node_postgres[("PostgreSQL<br/>relational database")]
  node_schema["Database schema<br/>SQL schema<br/>[create_schema.sql]"]
  node_exercise_seed["Exercise seed<br/>data provisioning<br/>[seed_exercises.py]"]
end

node_runner -->|"starts"| node_app
node_app -->|"registers"| node_identity
node_app -->|"registers"| node_login
node_app -->|"registers"| node_plans
node_app -->|"registers"| node_schedules
node_app -->|"registers"| node_logs
node_app -->|"registers"| node_reports
node_app -->|"registers"| node_exercises
node_app -->|"serves /docs"| node_api_docs
node_login -->|"issues JWTs"| node_security
node_identity -->|"current user"| node_security
node_plans -->|"authorizes"| node_security
node_schedules -->|"authorizes"| node_security
node_logs -->|"authorizes"| node_security
node_reports -->|"scopes queries"| node_security
node_plans -->|"validates"| node_plan_contracts
node_schedules -->|"validates"| node_schedule_contracts
node_logs -->|"validates"| node_log_contracts
node_plans -->|"persists plans"| node_db_connection
node_schedules -->|"persists schedules"| node_db_connection
node_logs -->|"persists sessions"| node_db_connection
node_reports -->|"reads history"| node_db_connection
node_exercises -->|"queries catalog"| node_db_connection
node_identity -->|"persists accounts"| node_db_connection
node_db_connection -->|"loads settings"| node_config
node_db_connection -->|"connects"| node_postgres
node_schema -->|"creates tables"| node_postgres
node_exercise_seed -->|"loads catalog"| node_postgres
node_plans -->|"plans are scheduled as"| node_schedules
node_logs -->|"historical input"| node_reports

click node_runner "https://github.com/oluwatooki/workout-tracker/blob/main/app/run.py"
click node_app "https://github.com/oluwatooki/workout-tracker/blob/main/app/main.py"
click node_identity "https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/users.py"
click node_login "https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/login.py"
click node_plans "https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/workout.py"
click node_schedules "https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/scheduled_workouts.py"
click node_logs "https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/workout_logs.py"
click node_reports "https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/reports.py"
click node_exercises "https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/exercises.py"
click node_security "https://github.com/oluwatooki/workout-tracker/blob/main/app/core/security.py"
click node_config "https://github.com/oluwatooki/workout-tracker/blob/main/app/core/config.py"
click node_api_docs "https://github.com/oluwatooki/workout-tracker/blob/main/app/core/docs.py"
click node_plan_contracts "https://github.com/oluwatooki/workout-tracker/blob/main/app/schemas/workout_schemas.py"
click node_schedule_contracts "https://github.com/oluwatooki/workout-tracker/blob/main/app/schemas/scheduled_workouts_schemas.py"
click node_log_contracts "https://github.com/oluwatooki/workout-tracker/blob/main/app/schemas/logs_schemas.py"
click node_db_connection "https://github.com/oluwatooki/workout-tracker/blob/main/app/db/connection.py"
click node_schema "https://github.com/oluwatooki/workout-tracker/blob/main/app/db/scripts/create_schema.sql"
click node_exercise_seed "https://github.com/oluwatooki/workout-tracker/blob/main/app/db/seeds/seed_exercises.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_app toneBlue
class node_identity,node_login,node_plans,node_schedules,node_logs,node_reports,node_exercises toneAmber
class node_security,node_config,node_api_docs toneMint
class node_plan_contracts,node_schedule_contracts,node_log_contracts,node_db_connection,node_postgres,node_schema,node_exercise_seed toneRose
```

## Components

### Runtime

- [Local runner](https://github.com/oluwatooki/workout-tracker/blob/main/app/run.py): Python entrypoint · Starts the API locally. · `app/run.py`
- [FastAPI application](https://github.com/oluwatooki/workout-tracker/blob/main/app/main.py): application bootstrap · Composes and registers the REST API. · `app/main.py`

### API domains

- [Identity routes](https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/users.py): route handlers · Registration and current-user account access. · `app/endpoints/users.py`
- [Login routes](https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/login.py): route handlers · Authenticates users and returns JWTs. · `app/endpoints/login.py`
- [Workout plans](https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/workout.py): route handlers · Creates and manages user workout plans. · `app/endpoints/workout.py`
- [Scheduled workouts](https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/scheduled_workouts.py): route handlers · Manages planned workout instances. · `app/endpoints/scheduled_workouts.py`
- [Workout logs](https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/workout_logs.py): route handlers · Records completed workout sessions. · `app/endpoints/workout_logs.py`
- [Progress reports](https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/reports.py): query routes · Aggregates prior workout history. · `app/endpoints/reports.py`
- [Exercise catalog](https://github.com/oluwatooki/workout-tracker/blob/main/app/endpoints/exercises.py): route handlers · `app/endpoints/exercises.py`

### Core services

- [JWT security](https://github.com/oluwatooki/workout-tracker/blob/main/app/core/security.py): authentication service · Establishes the protected current-user boundary. · `app/core/security.py`
- [Configuration](https://github.com/oluwatooki/workout-tracker/blob/main/app/core/config.py): settings · Loads database and JWT environment values. · `app/core/config.py`
- [API documentation](https://github.com/oluwatooki/workout-tracker/blob/main/app/core/docs.py): documentation support · Supports the FastAPI documentation surface. · `app/core/docs.py`

### Data & contracts

- [Plan contracts](https://github.com/oluwatooki/workout-tracker/blob/main/app/schemas/workout_schemas.py): Pydantic schemas · `app/schemas/workout_schemas.py`
- [Schedule contracts](https://github.com/oluwatooki/workout-tracker/blob/main/app/schemas/scheduled_workouts_schemas.py): Pydantic schemas · `app/schemas/scheduled_workouts_schemas.py`
- [Log contracts](https://github.com/oluwatooki/workout-tracker/blob/main/app/schemas/logs_schemas.py): Pydantic schemas · `app/schemas/logs_schemas.py`
- [Database access](https://github.com/oluwatooki/workout-tracker/blob/main/app/db/connection.py): connection layer · Centralized application access to PostgreSQL. · `app/db/connection.py`
- **PostgreSQL**: relational database · Stores accounts, catalog, plans, schedules, and logs.
- [Database schema](https://github.com/oluwatooki/workout-tracker/blob/main/app/db/scripts/create_schema.sql): SQL schema · Explicit database schema creation. · `app/db/scripts/create_schema.sql`
- [Exercise seed](https://github.com/oluwatooki/workout-tracker/blob/main/app/db/seeds/seed_exercises.py): data provisioning · Provisions exercise catalog data. · `app/db/seeds/seed_exercises.py`

## Connections

- 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