# unknownkyut/thedgym architecture

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

- Interactive diagram: https://gitdiagram.com/unknownkyut/thedgym
- Repository: https://github.com/unknownkyut/thedgym

## Overview

The DGym is a gym membership and operations portal with NFC access monitoring, online payments, and churn analytics. Members and staff use the web portal for account access, memberships, visits, training, and management; the backend exposes those capabilities through FastAPI and persists operational and analytics data. The README documents the web/API deployment boundary, while source evidence shows startup wiring, database setup, and churn processing. Several feature routers and frontend pages are unsampled, so their internal call paths are not asserted.

Main entry points: [`backend/app/database.py`](https://github.com/unknownkyut/thedgym/blob/main/backend/app/database.py) (SQL database), [`backend/app/services/churn_pipeline.py`](https://github.com/unknownkyut/thedgym/blob/main/backend/app/services/churn_pipeline.py) (Churn pipeline), [`backend/app/main.py`](https://github.com/unknownkyut/thedgym/blob/main/backend/app/main.py) (FastAPI app), [`frontend/src/App.tsx`](https://github.com/unknownkyut/thedgym/blob/main/frontend/src/App.tsx) (React portal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web portal"]
  node_portal["React portal<br/>[App.tsx]"]
  node_client_api["API client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_app["FastAPI app<br/>[main.py]"]
  node_routers["Feature routers"]
  node_auth["Authentication<br/>[auth.py]"]
  node_access_routes["Access endpoints<br/>[access_control.py]"]
end

subgraph group_domain["Gym operations"]
  node_access_engine["NFC access engine<br/>[access_service.py]"]
  node_members["Member records<br/>[member.py]"]
  node_memberships["Membership records"]
  node_plans["Membership plans<br/>[membership_plan.py]"]
  node_classes["Class sessions<br/>[class_session.py]"]
  node_pt["PT sessions<br/>[pt_session.py]"]
  node_payments["Xendit payments<br/>[xendit_service.py]"]
  node_finance["Finance operations<br/>[finance.py]"]
end

subgraph group_insights["Analytics and retention"]
  node_analytics["Analytics endpoints<br/>[analytics.py]"]
  node_retention["Retention operations<br/>[retention.py]"]
  node_churn["Churn pipeline<br/>[churn_pipeline.py]"]
end

subgraph group_storage["Persistence and security"]
  node_security["Token security<br/>[security.py]"]
  node_db[("SQL database<br/>[database.py]")]
  node_audit["Audit logging<br/>[audit.py]"]
end

node_member(("Member"))
node_staff(("Gym staff"))

node_member -->|"uses"| node_portal
node_staff -->|"uses"| node_portal
node_portal -.->|"requests data"| node_client_api
node_portal -->|"API traffic"| node_app
node_app -->|"registers"| node_routers
node_app -->|"initializes"| node_db
node_app -->|"starts"| node_churn
node_auth -->|"uses tokens"| node_security
node_access_routes -.->|"dispatches taps"| node_access_engine
node_access_engine -->|"checks member"| node_members
node_access_engine -->|"checks status"| node_memberships
node_churn -->|"reads activity"| node_members
node_churn -->|"reads bookings"| node_classes
node_churn -->|"reads sessions"| node_pt
node_churn -->|"stores predictions"| node_db
node_members -->|"maps to tables"| node_db
node_memberships -->|"maps to tables"| node_db
node_plans -->|"maps to tables"| node_db
node_classes -->|"maps to tables"| node_db
node_pt -->|"maps to tables"| node_db
node_payments -->|"updates membership"| node_memberships

click node_portal "https://github.com/unknownkyut/thedgym/blob/main/frontend/src/App.tsx"
click node_client_api "https://github.com/unknownkyut/thedgym/blob/main/frontend/src/services/api.ts"
click node_app "https://github.com/unknownkyut/thedgym/blob/main/backend/app/main.py"
click node_routers "https://github.com/unknownkyut/thedgym/tree/main/backend/app/routers"
click node_auth "https://github.com/unknownkyut/thedgym/blob/main/backend/app/routers/auth.py"
click node_access_routes "https://github.com/unknownkyut/thedgym/blob/main/backend/app/routers/access_control.py"
click node_access_engine "https://github.com/unknownkyut/thedgym/blob/main/backend/app/services/access_service.py"
click node_members "https://github.com/unknownkyut/thedgym/blob/main/backend/app/models/member.py"
click node_memberships "https://github.com/unknownkyut/thedgym/blob/main/backend/app/models/member_membership.py"
click node_plans "https://github.com/unknownkyut/thedgym/blob/main/backend/app/models/membership_plan.py"
click node_classes "https://github.com/unknownkyut/thedgym/blob/main/backend/app/models/class_session.py"
click node_pt "https://github.com/unknownkyut/thedgym/blob/main/backend/app/models/pt_session.py"
click node_payments "https://github.com/unknownkyut/thedgym/blob/main/backend/app/services/xendit_service.py"
click node_finance "https://github.com/unknownkyut/thedgym/blob/main/backend/app/routers/finance.py"
click node_analytics "https://github.com/unknownkyut/thedgym/blob/main/backend/app/routers/analytics.py"
click node_retention "https://github.com/unknownkyut/thedgym/blob/main/backend/app/routers/retention.py"
click node_churn "https://github.com/unknownkyut/thedgym/blob/main/backend/app/services/churn_pipeline.py"
click node_security "https://github.com/unknownkyut/thedgym/blob/main/backend/app/core/security.py"
click node_db "https://github.com/unknownkyut/thedgym/blob/main/backend/app/database.py"
click node_audit "https://github.com/unknownkyut/thedgym/blob/main/backend/app/services/audit.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_portal,node_client_api toneBlue
class node_app,node_routers,node_auth,node_access_routes toneAmber
class node_access_engine,node_members,node_memberships,node_plans,node_classes,node_pt,node_payments,node_finance toneMint
class node_analytics,node_retention,node_churn toneRose
class node_security,node_db,node_audit,node_member,node_staff toneIndigo
```

## Components

### Web portal

- [React portal](https://github.com/unknownkyut/thedgym/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/unknownkyut/thedgym/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Backend API

- [FastAPI app](https://github.com/unknownkyut/thedgym/blob/main/backend/app/main.py): `backend/app/main.py`
- [Feature routers](https://github.com/unknownkyut/thedgym/tree/main/backend/app/routers): `backend/app/routers`
- [Authentication](https://github.com/unknownkyut/thedgym/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Access endpoints](https://github.com/unknownkyut/thedgym/blob/main/backend/app/routers/access_control.py): `backend/app/routers/access_control.py`

### Gym operations

- [NFC access engine](https://github.com/unknownkyut/thedgym/blob/main/backend/app/services/access_service.py): `backend/app/services/access_service.py`
- [Member records](https://github.com/unknownkyut/thedgym/blob/main/backend/app/models/member.py): `backend/app/models/member.py`
- [Membership records](https://github.com/unknownkyut/thedgym/blob/main/backend/app/models/member_membership.py): `backend/app/models/member_membership.py`
- [Membership plans](https://github.com/unknownkyut/thedgym/blob/main/backend/app/models/membership_plan.py): `backend/app/models/membership_plan.py`
- [Class sessions](https://github.com/unknownkyut/thedgym/blob/main/backend/app/models/class_session.py): `backend/app/models/class_session.py`
- [PT sessions](https://github.com/unknownkyut/thedgym/blob/main/backend/app/models/pt_session.py): `backend/app/models/pt_session.py`
- [Xendit payments](https://github.com/unknownkyut/thedgym/blob/main/backend/app/services/xendit_service.py): `backend/app/services/xendit_service.py`
- [Finance operations](https://github.com/unknownkyut/thedgym/blob/main/backend/app/routers/finance.py): `backend/app/routers/finance.py`

### Analytics and retention

- [Analytics endpoints](https://github.com/unknownkyut/thedgym/blob/main/backend/app/routers/analytics.py): `backend/app/routers/analytics.py`
- [Retention operations](https://github.com/unknownkyut/thedgym/blob/main/backend/app/routers/retention.py): `backend/app/routers/retention.py`
- [Churn pipeline](https://github.com/unknownkyut/thedgym/blob/main/backend/app/services/churn_pipeline.py): `backend/app/services/churn_pipeline.py`

### Persistence and security

- [Token security](https://github.com/unknownkyut/thedgym/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [SQL database](https://github.com/unknownkyut/thedgym/blob/main/backend/app/database.py): `backend/app/database.py`
- [Audit logging](https://github.com/unknownkyut/thedgym/blob/main/backend/app/services/audit.py): `backend/app/services/audit.py`

### Other components

- **Member**
- **Gym staff**

## Connections

- Member → React portal: uses (evidence: `README.md`)
- Gym staff → React portal: uses (evidence: `README.md`)
- React portal → API client: requests data
- React portal → FastAPI app: API traffic (evidence: `README.md`)
- FastAPI app → Feature routers: registers (evidence: `backend/app/main.py`)
- FastAPI app → SQL database: initializes (evidence: `backend/app/main.py`)
- FastAPI app → Churn pipeline: starts (evidence: `backend/app/main.py`)
- Authentication → Token security: uses tokens (evidence: `backend/app/routers/auth.py`)
- Access endpoints → NFC access engine: dispatches taps
- NFC access engine → Member records: checks member (evidence: `backend/app/services/access_service.py`)
- NFC access engine → Membership records: checks status (evidence: `backend/app/services/access_service.py`)
- Churn pipeline → Member records: reads activity (evidence: `backend/app/services/churn_pipeline.py`)
- Churn pipeline → Class sessions: reads bookings (evidence: `backend/app/services/churn_pipeline.py`)
- Churn pipeline → PT sessions: reads sessions (evidence: `backend/app/services/churn_pipeline.py`)
- Churn pipeline → SQL database: stores predictions (evidence: `backend/app/services/churn_pipeline.py`)
- Member records → SQL database: maps to tables (evidence: `backend/app/models/member.py`)
- Membership records → SQL database: maps to tables (evidence: `backend/app/models/member_membership.py`)
- Membership plans → SQL database: maps to tables (evidence: `backend/app/models/membership_plan.py`)
- Class sessions → SQL database: maps to tables (evidence: `backend/app/models/class_session.py`)
- PT sessions → SQL database: maps to tables (evidence: `backend/app/models/pt_session.py`)
- Xendit payments → Membership records: updates membership (evidence: `backend/app/services/xendit_service.py`)