# lorenzopietrangelo/openworkout-engine architecture

> Architecture diagram of the GitHub repository lorenzopietrangelo/openworkout-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lorenzopietrangelo/openworkout-engine
- Repository: https://github.com/lorenzopietrangelo/openworkout-engine

## Overview

OpenWorkout Engine builds deterministic weekly workout plans from training days, muscle priorities, session limits, equipment, and experience level. The main workflow runs through either the web interface and REST API or the Python script: inputs are validated, the engine schedules muscles and selects exercises, then adjusts sets and returns JSON or CSV. The README also documents advanced muscle regions, supersets, and unilateral variants. Source excerpts show API orchestration and engine behavior; some README-described details are not independently traced through unsampled code.

Main entry points: [`api_wrapper/service.py`](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/api_wrapper/service.py) (Plan and export service), [`api_wrapper/app.py`](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/api_wrapper/app.py) (FastAPI app), [`main.py`](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/main.py) (Python script), [`engine.py`](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/engine.py) (Planning and optimization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_web["Web interface<br/>[app.js]"]
  node_cli["Python script<br/>[main.py]"]
end

subgraph group_api["REST API"]
  node_app["FastAPI app<br/>[app.py]"]
  node_catalog_routes["Catalog routes<br/>[catalogo.py]"]
  node_plan_routes["Plan routes<br/>[scheda.py]"]
  node_schemas["Request and response models<br/>[schemas.py]"]
  node_service["Plan and export service<br/>[service.py]"]
end

subgraph group_engine["Workout engine"]
  node_engine["Planning and optimization<br/>[engine.py]"]
end

subgraph group_domain["Workout domain"]
  node_catalog["Exercise catalog<br/>[execises.py]"]
  node_model["Workout data model<br/>[exercise_model.py]"]
end

node_user(("Trainee"))

node_user -->|"sets preferences"| node_web
node_web -->|"calls API"| node_app
node_app -->|"registers routes"| node_catalog_routes
node_app -->|"registers routes"| node_plan_routes
node_app -->|"serves interface"| node_web
node_catalog_routes -->|"loads catalog"| node_service
node_catalog_routes -->|"uses enums"| node_model
node_plan_routes -->|"validates and responds"| node_schemas
node_plan_routes -->|"requests plan or CSV"| node_service
node_service -->|"builds and optimizes"| node_engine
node_service -->|"uses exercises"| node_catalog
node_service -->|"builds API output"| node_schemas
node_engine -->|"selects exercises"| node_catalog
node_engine -->|"uses workout types"| node_model
node_catalog -->|"defines exercises"| node_model
node_cli -->|"builds and optimizes"| node_engine
node_cli -->|"uses exercises"| node_catalog
node_cli -->|"sets input types"| node_model
node_user -->|"configures inputs"| node_cli

click node_web "https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/frontend/app.js"
click node_cli "https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/main.py"
click node_app "https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/api_wrapper/app.py"
click node_catalog_routes "https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/api_wrapper/routers/catalogo.py"
click node_plan_routes "https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/api_wrapper/routers/scheda.py"
click node_schemas "https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/api_wrapper/schemas.py"
click node_service "https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/api_wrapper/service.py"
click node_engine "https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/engine.py"
click node_catalog "https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/execises.py"
click node_model "https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/exercise_model.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_web,node_cli toneBlue
class node_app,node_catalog_routes,node_plan_routes,node_schemas,node_service toneAmber
class node_engine toneMint
class node_catalog,node_model toneRose
class node_user toneIndigo
```

## Components

### User interfaces

- [Web interface](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/frontend/app.js): `frontend/app.js`
- [Python script](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/main.py): `main.py`

### REST API

- [FastAPI app](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/api_wrapper/app.py): `api_wrapper/app.py`
- [Catalog routes](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/api_wrapper/routers/catalogo.py): `api_wrapper/routers/catalogo.py`
- [Plan routes](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/api_wrapper/routers/scheda.py): `api_wrapper/routers/scheda.py`
- [Request and response models](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/api_wrapper/schemas.py): `api_wrapper/schemas.py`
- [Plan and export service](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/api_wrapper/service.py): `api_wrapper/service.py`

### Workout engine

- [Planning and optimization](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/engine.py): `engine.py`

### Workout domain

- [Exercise catalog](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/execises.py): `execises.py`
- [Workout data model](https://github.com/lorenzopietrangelo/openworkout-engine/blob/main/exercise_model.py): `exercise_model.py`

### Other components

- **Trainee**

## Connections

- Trainee → Web interface: sets preferences (evidence: `README.md`)
- Web interface → FastAPI app: calls API (evidence: `frontend/app.js`)
- FastAPI app → Catalog routes: registers routes (evidence: `api_wrapper/app.py`)
- FastAPI app → Plan routes: registers routes (evidence: `api_wrapper/app.py`)
- FastAPI app → Web interface: serves interface (evidence: `api_wrapper/app.py`)
- Catalog routes → Plan and export service: loads catalog (evidence: `api_wrapper/routers/catalogo.py`)
- Catalog routes → Workout data model: uses enums (evidence: `api_wrapper/routers/catalogo.py`)
- Plan routes → Request and response models: validates and responds (evidence: `api_wrapper/routers/scheda.py`)
- Plan routes → Plan and export service: requests plan or CSV (evidence: `api_wrapper/routers/scheda.py`)
- Plan and export service → Planning and optimization: builds and optimizes (evidence: `api_wrapper/service.py`)
- Plan and export service → Exercise catalog: uses exercises (evidence: `api_wrapper/service.py`)
- Plan and export service → Request and response models: builds API output (evidence: `api_wrapper/service.py`)
- Planning and optimization → Exercise catalog: selects exercises (evidence: `engine.py`)
- Planning and optimization → Workout data model: uses workout types (evidence: `engine.py`)
- Exercise catalog → Workout data model: defines exercises (evidence: `execises.py`)
- Python script → Planning and optimization: builds and optimizes (evidence: `main.py`)
- Python script → Exercise catalog: uses exercises (evidence: `main.py`)
- Python script → Workout data model: sets input types (evidence: `main.py`)
- Trainee → Python script: configures inputs (evidence: `README.md`)
