# romka14/gym_bot architecture

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

- Interactive diagram: https://gitdiagram.com/romka14/gym_bot
- Repository: https://github.com/romka14/gym_bot

## Overview

Gym Tracker Bot is a Telegram workout tracker. The main workflow starts with a user creating a workout, selecting exercises, and logging sets; the bot can then finish the workout and provide history, statistics, and personal records. The graph separates Telegram interaction, domain services, persistence, and relational models. The README documents history and statistics capabilities, while excerpts show selected workout, reference-data, and persistence calls; unsampled details are represented only where documented, without inferred call edges.

Main entry points: [`app/database/connection.py`](https://github.com/romka14/gym_bot/blob/main/app/database/connection.py) (Async database session), [`app/main.py`](https://github.com/romka14/gym_bot/blob/main/app/main.py) (Command handlers), [`app/services/workout_service.py`](https://github.com/romka14/gym_bot/blob/main/app/services/workout_service.py) (Workout lifecycle), [`app/repositories/base.py`](https://github.com/romka14/gym_bot/blob/main/app/repositories/base.py) (CRUD repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram interface"]
  node_bot["Command handlers<br/>[main.py]"]
  node_fsm["Conversation state<br/>[states.py]"]
end

subgraph group_domain["Workout services"]
  node_user_service["User service<br/>[user_service.py]"]
  node_reference_service["Exercise catalog"]
  node_workout_service["Workout lifecycle<br/>[workout_service.py]"]
end

subgraph group_persistence["Persistence"]
  node_user_repo["User repository<br/>[user_repository.py]"]
  node_muscle_repo["Muscle group repository"]
  node_exercise_repo["Exercise repository"]
  node_base_repo["CRUD repository<br/>[base.py]"]
  node_db_session[("Async database session<br/>[connection.py]")]
end

subgraph group_schema["Workout data"]
  node_user_model["User records<br/>[user.py]"]
  node_muscle_model["Muscle groups<br/>[muscle_group.py]"]
  node_exercise_model["Exercise catalog<br/>[exercise.py]"]
  node_workout_model["Workouts<br/>[workout.py]"]
  node_workout_exercise_model["Workout exercises"]
  node_set_model["Workout sets<br/>[workout_set.py]"]
end

node_person(("Telegram user"))
node_telegram_api["Telegram Bot API"]

node_person -->|"sends commands"| node_telegram_api
node_telegram_api -->|"delivers updates"| node_bot
node_bot -->|"sends replies"| node_telegram_api
node_bot -->|"tracks conversation"| node_fsm
node_bot -->|"gets or creates"| node_user_service
node_bot -->|"loads catalog"| node_reference_service
node_bot -->|"manages workout"| node_workout_service
node_reference_service -->|"queries groups"| node_muscle_repo
node_reference_service -->|"queries exercises"| node_exercise_repo
node_user_service -->|"uses repository"| node_user_repo
node_workout_service -->|"queries and writes"| node_db_session
node_user_repo -->|"inherits CRUD"| node_base_repo
node_muscle_repo -->|"inherits CRUD"| node_base_repo
node_exercise_repo -->|"inherits CRUD"| node_base_repo
node_base_repo -->|"executes queries"| node_db_session
node_user_repo -->|"operates on"| node_user_model
node_muscle_repo -->|"operates on"| node_muscle_model
node_exercise_repo -->|"operates on"| node_exercise_model
node_db_session -->|"maps records"| node_user_model
node_db_session -->|"maps records"| node_muscle_model
node_db_session -->|"maps records"| node_exercise_model
node_db_session -->|"maps records"| node_workout_model
node_db_session -->|"maps records"| node_workout_exercise_model
node_db_session -->|"maps records"| node_set_model
node_workout_service -->|"creates and queries"| node_workout_model
node_workout_service -->|"adds exercises"| node_workout_exercise_model
node_workout_service -->|"adds sets"| node_set_model
node_workout_model -->|"relates exercises"| node_workout_exercise_model
node_workout_exercise_model -->|"contains sets"| node_set_model
node_muscle_model -->|"groups exercises"| node_exercise_model

click node_bot "https://github.com/romka14/gym_bot/blob/main/app/main.py"
click node_fsm "https://github.com/romka14/gym_bot/blob/main/app/states.py"
click node_user_service "https://github.com/romka14/gym_bot/blob/main/app/services/user_service.py"
click node_reference_service "https://github.com/romka14/gym_bot/blob/main/app/services/reference_service.py"
click node_workout_service "https://github.com/romka14/gym_bot/blob/main/app/services/workout_service.py"
click node_user_repo "https://github.com/romka14/gym_bot/blob/main/app/repositories/user_repository.py"
click node_muscle_repo "https://github.com/romka14/gym_bot/blob/main/app/repositories/muscle_group_repository.py"
click node_exercise_repo "https://github.com/romka14/gym_bot/blob/main/app/repositories/exercise_repository.py"
click node_base_repo "https://github.com/romka14/gym_bot/blob/main/app/repositories/base.py"
click node_db_session "https://github.com/romka14/gym_bot/blob/main/app/database/connection.py"
click node_user_model "https://github.com/romka14/gym_bot/blob/main/app/models/user.py"
click node_muscle_model "https://github.com/romka14/gym_bot/blob/main/app/models/muscle_group.py"
click node_exercise_model "https://github.com/romka14/gym_bot/blob/main/app/models/exercise.py"
click node_workout_model "https://github.com/romka14/gym_bot/blob/main/app/models/workout.py"
click node_workout_exercise_model "https://github.com/romka14/gym_bot/blob/main/app/models/workout_exercise.py"
click node_set_model "https://github.com/romka14/gym_bot/blob/main/app/models/workout_set.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_bot,node_fsm,node_person toneBlue
class node_user_service,node_reference_service,node_workout_service toneAmber
class node_user_repo,node_muscle_repo,node_exercise_repo,node_base_repo,node_db_session,node_telegram_api toneMint
class node_user_model,node_muscle_model,node_exercise_model,node_workout_model,node_workout_exercise_model,node_set_model toneRose
```

## Components

### Telegram interface

- [Command handlers](https://github.com/romka14/gym_bot/blob/main/app/main.py): `app/main.py`
- [Conversation state](https://github.com/romka14/gym_bot/blob/main/app/states.py): `app/states.py`

### Workout services

- [User service](https://github.com/romka14/gym_bot/blob/main/app/services/user_service.py): `app/services/user_service.py`
- [Exercise catalog](https://github.com/romka14/gym_bot/blob/main/app/services/reference_service.py): `app/services/reference_service.py`
- [Workout lifecycle](https://github.com/romka14/gym_bot/blob/main/app/services/workout_service.py): `app/services/workout_service.py`

### Persistence

- [User repository](https://github.com/romka14/gym_bot/blob/main/app/repositories/user_repository.py): `app/repositories/user_repository.py`
- [Muscle group repository](https://github.com/romka14/gym_bot/blob/main/app/repositories/muscle_group_repository.py): `app/repositories/muscle_group_repository.py`
- [Exercise repository](https://github.com/romka14/gym_bot/blob/main/app/repositories/exercise_repository.py): `app/repositories/exercise_repository.py`
- [CRUD repository](https://github.com/romka14/gym_bot/blob/main/app/repositories/base.py): `app/repositories/base.py`
- [Async database session](https://github.com/romka14/gym_bot/blob/main/app/database/connection.py): `app/database/connection.py`

### Workout data

- [User records](https://github.com/romka14/gym_bot/blob/main/app/models/user.py): `app/models/user.py`
- [Muscle groups](https://github.com/romka14/gym_bot/blob/main/app/models/muscle_group.py): `app/models/muscle_group.py`
- [Exercise catalog](https://github.com/romka14/gym_bot/blob/main/app/models/exercise.py): `app/models/exercise.py`
- [Workouts](https://github.com/romka14/gym_bot/blob/main/app/models/workout.py): `app/models/workout.py`
- [Workout exercises](https://github.com/romka14/gym_bot/blob/main/app/models/workout_exercise.py): `app/models/workout_exercise.py`
- [Workout sets](https://github.com/romka14/gym_bot/blob/main/app/models/workout_set.py): `app/models/workout_set.py`

### Other components

- **Telegram user**
- **Telegram Bot API**

## Connections

- Telegram user → Telegram Bot API: sends commands (evidence: `README.md`)
- Telegram Bot API → Command handlers: delivers updates (evidence: `app/main.py`)
- Command handlers → Telegram Bot API: sends replies (evidence: `app/main.py`)
- Command handlers → Conversation state: tracks conversation (evidence: `app/main.py`)
- Command handlers → User service: gets or creates (evidence: `app/main.py`)
- Command handlers → Exercise catalog: loads catalog (evidence: `app/main.py`)
- Command handlers → Workout lifecycle: manages workout (evidence: `app/main.py`)
- Exercise catalog → Muscle group repository: queries groups (evidence: `app/services/reference_service.py`)
- Exercise catalog → Exercise repository: queries exercises (evidence: `app/services/reference_service.py`)
- User service → User repository: uses repository
- Workout lifecycle → Async database session: queries and writes (evidence: `app/services/workout_service.py`)
- User repository → CRUD repository: inherits CRUD (evidence: `app/repositories/user_repository.py`)
- Muscle group repository → CRUD repository: inherits CRUD (evidence: `app/repositories/muscle_group_repository.py`)
- Exercise repository → CRUD repository: inherits CRUD (evidence: `app/repositories/exercise_repository.py`)
- CRUD repository → Async database session: executes queries (evidence: `app/repositories/base.py`)
- User repository → User records: operates on (evidence: `app/repositories/user_repository.py`)
- Muscle group repository → Muscle groups: operates on (evidence: `app/repositories/muscle_group_repository.py`)
- Exercise repository → Exercise catalog: operates on (evidence: `app/repositories/exercise_repository.py`)
- Async database session → User records: maps records (evidence: `app/models/user.py`)
- Async database session → Muscle groups: maps records (evidence: `app/models/muscle_group.py`)
- Async database session → Exercise catalog: maps records (evidence: `app/models/exercise.py`)
- Async database session → Workouts: maps records (evidence: `app/models/workout.py`)
- Async database session → Workout exercises: maps records (evidence: `app/models/workout_exercise.py`)
- Async database session → Workout sets: maps records (evidence: `app/models/workout_set.py`)
- Workout lifecycle → Workouts: creates and queries (evidence: `app/services/workout_service.py`)
- Workout lifecycle → Workout exercises: adds exercises (evidence: `app/services/workout_service.py`)
- Workout lifecycle → Workout sets: adds sets (evidence: `app/services/workout_service.py`)
- Workouts → Workout exercises: relates exercises (evidence: `app/models/workout.py`)
- Workout exercises → Workout sets: contains sets (evidence: `app/models/workout_exercise.py`)
- Muscle groups → Exercise catalog: groups exercises (evidence: `app/models/muscle_group.py`)
