# fitlogic-gymapp/gympro architecture

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

- Interactive diagram: https://gitdiagram.com/fitlogic-gymapp/gympro
- Repository: https://github.com/fitlogic-gymapp/gympro

## Overview

1. **System boundary**
   - GymPro is a three-part system: a **Flask REST backend**, a **Flutter cross-platform member app**, and a **browser-based admin panel**.
   - All user-facing clients communicate with the backend over HTTP/JSON; the clients do **not** talk to the database directly.

2. **Backend core**
   - The backend is the central orchestration layer in `backend/app.py`.
   - It exposes REST endpoints for authentication, gym membership data, workouts, turnstile events, and admin CRUD operations.
   - CORS is enabled so both the Flutter app and the admin panel can call the API from different origins.

3. **Persistence layer**
   - The backend uses **MySQL** via **ODBC/pyodbc**.
   - `backend/createDB.sql` defines the schema; `backend/populate_saas.py` seeds sample SaaS-style tenant data.
   - `backend/.env.example` shows environment-based DB configuration, including host, database name, user, and password.

4. **Multi-tenant data model**
   - The repo is built around a **single global member account** plus **per-gym membership records**.
   - The key boundary is the `Membership` table, which links a member to one or more gyms and allows gym-specific access, occupancy, and workout context.
   - Gym-specific entities include trainers, admins, and settings tied to a gym ID.

5. **Mobile app**
   - `frontend/` is a **Flutter** app targeting Android, iOS, web, desktop, and mobile shells from one codebase.
   - Its architecture is split into `core/`, `features/`, and `shared/`, with Provider-based state management and GoRouter-style navigation implied by the README and file layout.
   - The mobile app is the member-facing client for login, gym selection, home dashboard, trainers, workouts, profile, and QR turnstile actions.

6. **Frontend data flow**
   - UI screens call feature-specific providers, which call shared services, which then call the backend API.
   - `frontend/lib/core/services/api_service.dart` is the main HTTP abstraction; `auth_service.dart` and `turnstile_service.dart` are specialized integrations.
   - This layering keeps UI widgets separate from network logic and authentication/session concerns.

7. **Member experience features**
   - The Flutter app contains distinct feature slices for:
     - authentication and gym selection,
     - home/dashboard,
     - trainers,
     - workouts,
     - profile,
     - QR entry/exit turnstile screens.
   - `home_provider.dart`, `trainers_provider.dart`, and `workouts_provider.dart` indicate the app is state-driven, likely refreshing server data into UI models.

8. **Turnstile subsystem**
   - The turnstile flow is a separate functional area, not just a UI screen.
   - `qr_entry_screen.dart` and `qr_exit_screen.dart` feed check-in/check-out requests to the backend, which records `TurnstileEvent` rows and updates occupancy-related views/data.
   - This subsystem is central to “real-time gym occupancy” in the product description.

9. **Admin panel**
   - `admin-panel/` is a lightweight web UI built with **HTML + vanilla JavaScript**.
   - It likely consumes the same REST API to manage exercises, workout programs, trainers, members, and gym settings.
   - This is an operational back-office boundary separate from the member-facing Flutter app.

10. **Reporting and derived data**
    - The database includes views such as `ActiveMembersView`, `TrainersInGymView`, `GymStatsView`, `TodayEntriesView`, and `MemberWorkoutSummaryView`.
    - These suggest the backend often reads precomputed or SQL-aggregated data for dashboards and list screens rather than assembling everything in application code.

11. **Security and identity**
    - Authentication is handled centrally via `POST /api/register` and `POST /api/login`.
    - The same authenticated identity is then reused across gym membership selection, workout data, and turnstile operations.
    - The architecture implies role separation between members and gym admins, with admin endpoints grouped under `/api/admin/...`.

12. **Supporting tooling**
    - `backend/test_api.py` provides API-level testing for the Flask service.
    - The Flutter tree includes platform shells for Android, iOS, web, macOS, Windows, and Linux, but the architectural center remains the shared Dart app code.
    - The overall deployment model is simple: a locally run Flask API, a MySQL database, and independently launched client apps.

Main entry points: [`backend/app.py`](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py) (Flask API), [`frontend/lib/core/providers/auth_provider.dart`](https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/core/providers/auth_provider.dart) (State providers), [`frontend/lib/features/auth/screens/login_screen.dart`](https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/features/auth/screens/login_screen.dart) (Feature screens), [`frontend/lib/shared/navigation/main_navigation_shell.dart`](https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/shared/navigation/main_navigation_shell.dart) (Navigation shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_backend["Backend"]
  node_node_backend_app["Flask API<br/>backend app<br/>[app.py]"]
  node_node_backend_cors(("CORS<br/>api middleware<br/>[app.py]"))
  node_node_backend_auth["Auth routes<br/>REST auth<br/>[app.py]"]
  node_node_backend_membership["Membership routes<br/>REST domain<br/>[app.py]"]
  node_node_backend_workouts["Workout routes<br/>REST domain<br/>[app.py]"]
  node_node_backend_turnstile["Turnstile routes<br/>REST events<br/>[app.py]"]
  node_node_backend_admin["Admin routes<br/>REST admin<br/>[app.py]"]
  node_node_backend_db[("MySQL access<br/>pyodbc persistence<br/>[app.py]")]
end

subgraph group_group_frontend["Flutter app"]
  node_node_flutter_app["Flutter app<br/>cross-platform client<br/>[main.dart]"]
  node_node_flutter_nav["Navigation shell<br/>app shell"]
  node_node_flutter_api["API service<br/>http client<br/>[api_service.dart]"]
  node_node_flutter_auth["Auth service<br/>session client<br/>[auth_service.dart]"]
  node_node_flutter_turnstile["Turnstile service<br/>qr client"]
  node_node_flutter_providers["State providers<br/>state layer<br/>[auth_provider.dart]"]
  node_node_flutter_features["Feature screens<br/>ui features<br/>[login_screen.dart]"]
  node_node_flutter_models["Feature models<br/>ui models<br/>[home_models.dart]"]
end

subgraph group_group_admin["Admin panel"]
  node_node_admin_ui["Admin UI<br/>vanilla web ui<br/>[index.html]"]
  node_node_admin_js["Admin script<br/>browser logic<br/>[app.js]"]
end

subgraph group_group_data["Data layer"]
  node_node_schema["Schema SQL<br/>mysql schema<br/>[createDB.sql]"]
  node_node_seed["Seed data<br/>data seeding<br/>[populate_saas.py]"]
  node_node_env["DB config<br/>env example<br/>[.env.example]"]
  node_node_views[("Reporting views<br/>sql views<br/>[createDB.sql]")]
end

node_node_backend_app -->|"enables"| node_node_backend_cors
node_node_backend_app -->|"serves"| node_node_backend_auth
node_node_backend_app -->|"serves"| node_node_backend_membership
node_node_backend_app -->|"serves"| node_node_backend_workouts
node_node_backend_app -->|"serves"| node_node_backend_turnstile
node_node_backend_app -->|"serves"| node_node_backend_admin
node_node_backend_app -->|"reads/writes"| node_node_backend_db
node_node_backend_db -->|"uses"| node_node_schema
node_node_backend_db -->|"queries"| node_node_views
node_node_seed -->|"loads"| node_node_schema
node_node_env -->|"configures"| node_node_backend_db
node_node_flutter_app -->|"uses"| node_node_flutter_nav
node_node_flutter_nav -->|"hosts"| node_node_flutter_features
node_node_flutter_features -->|"reads state"| node_node_flutter_providers
node_node_flutter_providers -->|"calls"| node_node_flutter_api
node_node_flutter_providers -->|"uses"| node_node_flutter_auth
node_node_flutter_providers -->|"uses"| node_node_flutter_turnstile
node_node_flutter_api -->|"HTTP/JSON"| node_node_backend_app
node_node_flutter_auth -->|"HTTP/JSON"| node_node_backend_auth
node_node_flutter_turnstile -->|"HTTP/JSON"| node_node_backend_turnstile
node_node_flutter_features -->|"shapes data"| node_node_flutter_models
node_node_admin_ui -->|"runs"| node_node_admin_js
node_node_admin_js -->|"HTTP/JSON"| node_node_backend_app
node_node_backend_turnstile -.->|"updates/readers"| node_node_views

click node_node_backend_app "https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py"
click node_node_backend_cors "https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py"
click node_node_backend_auth "https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py"
click node_node_backend_membership "https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py"
click node_node_backend_workouts "https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py"
click node_node_backend_turnstile "https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py"
click node_node_backend_admin "https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py"
click node_node_backend_db "https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py"
click node_node_schema "https://github.com/fitlogic-gymapp/gympro/blob/main/backend/createDB.sql"
click node_node_seed "https://github.com/fitlogic-gymapp/gympro/blob/main/backend/populate_saas.py"
click node_node_env "https://github.com/fitlogic-gymapp/gympro/blob/main/backend/.env.example"
click node_node_views "https://github.com/fitlogic-gymapp/gympro/blob/main/backend/createDB.sql"
click node_node_flutter_app "https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/main.dart"
click node_node_flutter_nav "https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/shared/navigation/main_navigation_shell.dart"
click node_node_flutter_api "https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/core/services/api_service.dart"
click node_node_flutter_auth "https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/core/services/auth_service.dart"
click node_node_flutter_turnstile "https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/core/services/turnstile_service.dart"
click node_node_flutter_providers "https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/core/providers/auth_provider.dart"
click node_node_flutter_features "https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/features/auth/screens/login_screen.dart"
click node_node_flutter_models "https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/features/home/models/home_models.dart"
click node_node_admin_ui "https://github.com/fitlogic-gymapp/gympro/blob/main/admin-panel/index.html"
click node_node_admin_js "https://github.com/fitlogic-gymapp/gympro/blob/main/admin-panel/app.js"

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_node_backend_app,node_node_backend_cors,node_node_backend_auth,node_node_backend_membership,node_node_backend_workouts,node_node_backend_turnstile,node_node_backend_admin,node_node_backend_db toneBlue
class node_node_flutter_app,node_node_flutter_nav,node_node_flutter_api,node_node_flutter_auth,node_node_flutter_turnstile,node_node_flutter_providers,node_node_flutter_features,node_node_flutter_models toneAmber
class node_node_admin_ui,node_node_admin_js toneMint
class node_node_schema,node_node_seed,node_node_env,node_node_views toneRose
```

## Components

### Backend

Flask API, persistence, and derived reporting.

- [Flask API](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py): backend app · Central REST orchestration layer exposing auth, membership, workouts, turnstile, and admin endpoints. · `backend/app.py`
- [CORS](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py): api middleware · Enables browser and Flutter clients to call the API from different origins. · `backend/app.py`
- [Auth routes](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py): REST auth · Register and login entry points for the shared user identity. · `backend/app.py`
- [Membership routes](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py): REST domain · Gym selection and member-to-gym access context. · `backend/app.py`
- [Workout routes](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py): REST domain · Workout program and member workout data served to the app. · `backend/app.py`
- [Turnstile routes](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py): REST events · Check-in and check-out endpoints that record gym entry events. · `backend/app.py`
- [Admin routes](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py): REST admin · Gym administration endpoints for CRUD-style operations. · `backend/app.py`
- [MySQL access](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/app.py): pyodbc persistence · Database connectivity through ODBC/pyodbc from the Flask service. · `backend/app.py`

### Flutter app

Shared Dart app for gym members across platforms.

- [Flutter app](https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/main.dart): cross-platform client · Shared member-facing app for mobile and desktop/web shells. · `frontend/lib/main.dart`
- [Navigation shell](https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/shared/navigation/main_navigation_shell.dart): app shell · Main navigation and routing container for the member experience. · `frontend/lib/shared/navigation/main_navigation_shell.dart`
- [API service](https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/core/services/api_service.dart): http client · Primary HTTP abstraction used by feature providers. · `frontend/lib/core/services/api_service.dart`
- [Auth service](https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/core/services/auth_service.dart): session client · Specialized authentication and session flow handling. · `frontend/lib/core/services/auth_service.dart`
- [Turnstile service](https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/core/services/turnstile_service.dart): qr client · QR entry and exit request integration for check-in workflows. · `frontend/lib/core/services/turnstile_service.dart`
- [State providers](https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/core/providers/auth_provider.dart): state layer · Provider-based state for auth, home, trainers, workouts, and turnstile flows. · `frontend/lib/core/providers/auth_provider.dart`
- [Feature screens](https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/features/auth/screens/login_screen.dart): ui features · Member-facing screens for login, gym selection, home, trainers, workouts, profile, and QR actions. · `frontend/lib/features/auth/screens/login_screen.dart`
- [Feature models](https://github.com/fitlogic-gymapp/gympro/blob/main/frontend/lib/features/home/models/home_models.dart): ui models · Typed data models for home, trainers, and workouts. · `frontend/lib/features/home/models/home_models.dart`

### Admin panel

Browser-based back-office UI.

- [Admin UI](https://github.com/fitlogic-gymapp/gympro/blob/main/admin-panel/index.html): vanilla web ui · Lightweight browser interface for back-office gym management. · `admin-panel/index.html`
- [Admin script](https://github.com/fitlogic-gymapp/gympro/blob/main/admin-panel/app.js): browser logic · Client-side JavaScript wiring for the admin panel. · `admin-panel/app.js`

### Data layer

MySQL schema, seed data, and reporting views.

- [Schema SQL](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/createDB.sql): mysql schema · Defines tables, relations, and reporting views for the SaaS-style gym data model. · `backend/createDB.sql`
- [Seed data](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/populate_saas.py): data seeding · Populates sample tenant and membership data. · `backend/populate_saas.py`
- [DB config](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/.env.example): env example · Environment-based connection settings for host, database, user, and password. · `backend/.env.example`
- [Reporting views](https://github.com/fitlogic-gymapp/gympro/blob/main/backend/createDB.sql): sql views · Precomputed views for active members, trainers, stats, today entries, and workout summaries. · `backend/createDB.sql`

## Connections

- Flask API → CORS: enables · API is exposed with cross-origin access for both clients.
- Flask API → Auth routes: serves · Handles register and login requests.
- Flask API → Membership routes: serves · Exposes gym selection and membership context.
- Flask API → Workout routes: serves · Returns workout-related member and program data.
- Flask API → Turnstile routes: serves · Records entry and exit events.
- Flask API → Admin routes: serves · Provides admin CRUD endpoints.
- Flask API → MySQL access: reads/writes · Uses MySQL through ODBC/pyodbc.
- MySQL access → Schema SQL: uses · Persists to the defined schema.
- MySQL access → Reporting views: queries · Reads aggregated reporting views for dashboards and lists.
- Seed data → Schema SQL: loads · Seeds data into the defined tables.
- DB config → MySQL access: configures · Supplies connection parameters for the database layer.
- Flutter app → Navigation shell: uses · Entrypoint hands off to the shared navigation shell.
- Navigation shell → Feature screens: hosts · Switches between member screens and feature areas.
- Feature screens → State providers: reads state · Screens consume provider-driven app state.
- State providers → API service: calls · Feature state loads and refreshes server data through the API service.
- State providers → Auth service: uses · Authentication and session logic is centralized.
- State providers → Turnstile service: uses · QR check-in and check-out flows call the specialized service.
- API service → Flask API: HTTP/JSON · Member app communicates with the Flask backend over REST.
- Auth service → Auth routes: HTTP/JSON · Login and registration requests go to auth endpoints.
- Turnstile service → Turnstile routes: HTTP/JSON · Entry and exit scans are submitted to turnstile endpoints.
- Feature screens → Feature models: shapes data · Feature screens render typed home, trainer, and workout models.
- Admin UI → Admin script: runs · HTML shell loads the browser-side admin logic.
- Admin script → Flask API: HTTP/JSON · Admin panel consumes the same REST API as the mobile app.
- Turnstile routes → Reporting views: updates/readers · Turnstile events feed occupancy and today-entry reporting.
