# chatpimuk07/smart_gym architecture

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

- Interactive diagram: https://gitdiagram.com/chatpimuk07/smart_gym
- Repository: https://github.com/chatpimuk07/smart_gym

## Overview

Smart Gym NFC Hub is a FastAPI-backed gym system: members identify at an ESP32 station by NFC tap, then receive a cached or newly generated, safety-aware routine; members can also request routines and track workouts through the web portal. Admins manage member records and scan cards, while public and member dashboards poll station status. The principal backend, AI, database and NFC modules are excerpted; unsampled routes and templates are represented only where README or shown references support them, so uncertain implementation links are omitted.

Main entry points: [`main.py`](https://github.com/chatpimuk07/smart_gym/blob/main/main.py) (FastAPI Routes), [`services/database.py`](https://github.com/chatpimuk07/smart_gym/blob/main/services/database.py) (Gym Database), [`static/user.js`](https://github.com/chatpimuk07/smart_gym/blob/main/static/user.js) (Member Portal), [`static/admin.js`](https://github.com/chatpimuk07/smart_gym/blob/main/static/admin.js) (Admin Portal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Interfaces"]
  node_esp32["ESP32 Station<br/>[station.ino]"]
  node_member_portal["Member Portal<br/>[user.js]"]
  node_member_page["Member Dashboard<br/>[user.html]"]
  node_admin_portal["Admin Portal<br/>[admin.js]"]
  node_admin_page["Admin Dashboard<br/>[admin.html]"]
  node_station_board["Station Status Board<br/>[stations.js]"]
  node_station_page["Station Status Page<br/>[stations.html]"]
end

subgraph group_api["API Workflows"]
  node_api_app["FastAPI Routes<br/>[main.py]"]
  node_routine_flow["Routine Generation<br/>[main.py]"]
  node_member_admin["Member Management<br/>[main.py]"]
  node_portal_auth["Member Auth &amp; Profile<br/>[main.py]"]
  node_workout_tracking["Workout Logging<br/>[main.py]"]
  node_station_status["Station Status API<br/>[main.py]"]
  node_nfc_scan_api["Admin NFC Scan API<br/>[main.py]"]
end

subgraph group_services["Core Services"]
  node_ai["Gemini Routine Service<br/>[ai_service.py]"]
  node_nfc_reader["USB PN532 Reader<br/>[nfc_reader.py]"]
end

subgraph group_state["Gym State"]
  node_database[("Gym Database<br/>[database.py]")]
end

node_member(("Gym Member"))
node_admin(("Gym Admin"))
node_gemini["Google Gemini"]

node_member -->|"taps NFC"| node_esp32
node_esp32 -->|"requests routine"| node_routine_flow
node_member -->|"uses portal"| node_member_portal
node_admin -->|"manages members"| node_admin_portal
node_member_portal -->|"calls API"| node_api_app
node_admin_portal -->|"submits member changes"| node_member_admin
node_admin_portal -->|"requests card scan"| node_nfc_scan_api
node_station_board -->|"polls status"| node_station_status
node_member_portal -->|"polls status"| node_station_status
node_api_app -->|"serves page"| node_member_page
node_api_app -->|"serves page"| node_admin_page
node_api_app -->|"serves page"| node_station_page
node_api_app -->|"routes requests"| node_routine_flow
node_routine_flow -->|"loads member, station, history"| node_database
node_routine_flow -->|"generates plan"| node_ai
node_ai -->|"requests generation"| node_gemini
node_routine_flow -.->|"uses daily cache"| node_database
node_api_app -->|"routes admin requests"| node_member_admin
node_member_admin -->|"creates, edits, deletes"| node_database
node_api_app -->|"routes portal requests"| node_portal_auth
node_portal_auth -->|"authenticates members"| node_database
node_api_app -.->|"routes workout logs"| node_workout_tracking
node_workout_tracking -.->|"records history"| node_database
node_api_app -->|"routes status requests"| node_station_status
node_station_status -->|"reads station state"| node_database
node_api_app -->|"routes scan requests"| node_nfc_scan_api
node_nfc_scan_api -->|"scans card"| node_nfc_reader

click node_esp32 "https://github.com/chatpimuk07/smart_gym/blob/main/esp32/src/station.ino"
click node_member_portal "https://github.com/chatpimuk07/smart_gym/blob/main/static/user.js"
click node_member_page "https://github.com/chatpimuk07/smart_gym/blob/main/templates/user.html"
click node_admin_portal "https://github.com/chatpimuk07/smart_gym/blob/main/static/admin.js"
click node_admin_page "https://github.com/chatpimuk07/smart_gym/blob/main/templates/admin.html"
click node_station_board "https://github.com/chatpimuk07/smart_gym/blob/main/static/stations.js"
click node_station_page "https://github.com/chatpimuk07/smart_gym/blob/main/templates/stations.html"
click node_api_app "https://github.com/chatpimuk07/smart_gym/blob/main/main.py"
click node_routine_flow "https://github.com/chatpimuk07/smart_gym/blob/main/main.py"
click node_member_admin "https://github.com/chatpimuk07/smart_gym/blob/main/main.py"
click node_portal_auth "https://github.com/chatpimuk07/smart_gym/blob/main/main.py"
click node_workout_tracking "https://github.com/chatpimuk07/smart_gym/blob/main/main.py"
click node_station_status "https://github.com/chatpimuk07/smart_gym/blob/main/main.py"
click node_nfc_scan_api "https://github.com/chatpimuk07/smart_gym/blob/main/main.py"
click node_ai "https://github.com/chatpimuk07/smart_gym/blob/main/services/ai_service.py"
click node_nfc_reader "https://github.com/chatpimuk07/smart_gym/blob/main/services/nfc_reader.py"
click node_database "https://github.com/chatpimuk07/smart_gym/blob/main/services/database.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_esp32,node_member_portal,node_member_page,node_admin_portal,node_admin_page,node_station_board,node_station_page toneBlue
class node_api_app,node_routine_flow,node_member_admin,node_portal_auth,node_workout_tracking,node_station_status,node_nfc_scan_api toneAmber
class node_ai,node_nfc_reader toneMint
class node_database toneRose
class node_member,node_admin,node_gemini toneIndigo
```

## Components

### User Interfaces

- [ESP32 Station](https://github.com/chatpimuk07/smart_gym/blob/main/esp32/src/station.ino): `esp32/src/station.ino`
- [Member Portal](https://github.com/chatpimuk07/smart_gym/blob/main/static/user.js): `static/user.js`
- [Member Dashboard](https://github.com/chatpimuk07/smart_gym/blob/main/templates/user.html): `templates/user.html`
- [Admin Portal](https://github.com/chatpimuk07/smart_gym/blob/main/static/admin.js): `static/admin.js`
- [Admin Dashboard](https://github.com/chatpimuk07/smart_gym/blob/main/templates/admin.html): `templates/admin.html`
- [Station Status Board](https://github.com/chatpimuk07/smart_gym/blob/main/static/stations.js): `static/stations.js`
- [Station Status Page](https://github.com/chatpimuk07/smart_gym/blob/main/templates/stations.html): `templates/stations.html`

### API Workflows

- [FastAPI Routes](https://github.com/chatpimuk07/smart_gym/blob/main/main.py): `main.py`
- [Routine Generation](https://github.com/chatpimuk07/smart_gym/blob/main/main.py): `main.py`
- [Member Management](https://github.com/chatpimuk07/smart_gym/blob/main/main.py): `main.py`
- [Member Auth & Profile](https://github.com/chatpimuk07/smart_gym/blob/main/main.py): `main.py`
- [Workout Logging](https://github.com/chatpimuk07/smart_gym/blob/main/main.py): `main.py`
- [Station Status API](https://github.com/chatpimuk07/smart_gym/blob/main/main.py): `main.py`
- [Admin NFC Scan API](https://github.com/chatpimuk07/smart_gym/blob/main/main.py): `main.py`

### Core Services

- [Gemini Routine Service](https://github.com/chatpimuk07/smart_gym/blob/main/services/ai_service.py): `services/ai_service.py`
- [USB PN532 Reader](https://github.com/chatpimuk07/smart_gym/blob/main/services/nfc_reader.py): `services/nfc_reader.py`

### Gym State

- [Gym Database](https://github.com/chatpimuk07/smart_gym/blob/main/services/database.py): `services/database.py`

### Other components

- **Gym Member**
- **Gym Admin**
- **Google Gemini**

## Connections

- Gym Member → ESP32 Station: taps NFC (evidence: `README.md`)
- ESP32 Station → Routine Generation: requests routine (evidence: `README.md`)
- Gym Member → Member Portal: uses portal (evidence: `README.md`)
- Gym Admin → Admin Portal: manages members (evidence: `README.md`)
- Member Portal → FastAPI Routes: calls API (evidence: `static/user.js`)
- Admin Portal → Member Management: submits member changes (evidence: `static/admin.js`)
- Admin Portal → Admin NFC Scan API: requests card scan (evidence: `static/admin.js`)
- Station Status Board → Station Status API: polls status (evidence: `static/stations.js`)
- Member Portal → Station Status API: polls status (evidence: `README.md`)
- FastAPI Routes → Member Dashboard: serves page (evidence: `main.py`)
- FastAPI Routes → Admin Dashboard: serves page (evidence: `main.py`)
- FastAPI Routes → Station Status Page: serves page (evidence: `main.py`)
- FastAPI Routes → Routine Generation: routes requests (evidence: `main.py`)
- Routine Generation → Gym Database: loads member, station, history (evidence: `main.py`)
- Routine Generation → Gemini Routine Service: generates plan (evidence: `main.py`)
- Gemini Routine Service → Google Gemini: requests generation (evidence: `services/ai_service.py`)
- Routine Generation → Gym Database: uses daily cache (evidence: `README.md`)
- FastAPI Routes → Member Management: routes admin requests (evidence: `main.py`)
- Member Management → Gym Database: creates, edits, deletes (evidence: `main.py`)
- FastAPI Routes → Member Auth & Profile: routes portal requests (evidence: `main.py`)
- Member Auth & Profile → Gym Database: authenticates members (evidence: `main.py`)
- FastAPI Routes → Workout Logging: routes workout logs (evidence: `main.py`)
- Workout Logging → Gym Database: records history (evidence: `README.md`)
- FastAPI Routes → Station Status API: routes status requests (evidence: `main.py`)
- Station Status API → Gym Database: reads station state (evidence: `main.py`)
- FastAPI Routes → Admin NFC Scan API: routes scan requests (evidence: `main.py`)
- Admin NFC Scan API → USB PN532 Reader: scans card (evidence: `main.py`)
