# urbanzi-solution/gym-app-version2 architecture

> Architecture diagram of the GitHub repository urbanzi-solution/gym-app-version2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urbanzi-solution/gym-app-version2
- Repository: https://github.com/urbanzi-solution/gym-app-version2

## Overview

1. This repository is a single Next.js application built around a gym/fitness management domain. It uses the App Router under `src/app` and combines UI pages, API routes, and shared client components in one codebase.

2. The front end is organized by business area: `Dashboard`, `Members`, `Trainers`, `Plans`, `Report`, `Settings`, plus dedicated login and profile pages. Each page is mostly a composition shell that pulls in reusable components from `src/components`.

3. Most interactive UI is split into feature components rather than page-local logic. Examples include member/trainer forms, profile panels, list filters, attendance tables, dashboard cards, report graphs, WhatsApp modals, and settings widgets. This suggests the app is a form-heavy admin console with many data-driven views.

4. The backend is exposed through a large set of route handlers under `src/app/api`. These endpoints cover CRUD for members, trainers, plans, transactions, attendance, balances, blacklists, profile photos, and renewal flows, plus export/download endpoints for lists and reports.

5. Data access is centralized through `src/lib/db.js`, which is the shared persistence boundary for the API layer. The presence of sequence/format endpoints for member IDs, trainer IDs, and bill numbers indicates the database stores both operational records and configurable numbering rules.

6. Authentication is a first-class subsystem. The repo includes `login` and `logout` API routes, `src/lib/auth.js`, `src/lib/jwt.js`, and `src/middleware.js`, implying protected routes and server-side auth checks are enforced across pages and APIs.

7. Member and trainer lifecycle management are separate but parallel domains. Both support create/edit/delete flows, custom ID generation, profile pictures, biodata/profile screens, attendance tracking, and blacklist operations, showing the app manages two primary person entities with similar workflows.

8. Attendance and billing are core transaction flows. There are dedicated endpoints for member/client/trainer attendance, balance adjustments, renewals, bill customization, write-offs, and auto-fill/fetch helpers, which points to a workflow where operational actions are recorded and later surfaced in reports and profiles.

9. Reporting is split into summary and detail layers. Dashboard-specific endpoints provide stats and “expiring soon” data, while the report module has transaction feeds, stat cards, graphs, and downloadable exports. This creates a read-optimized analytics path separate from the transactional CRUD routes.

10. Profile pages are their own subsystem rather than just filtered lists. `MemberProfile` and `TrainerProfile` have dedicated client components and API endpoints for details, recent activity, active plans, attendance, and recent transactions, indicating the app supports deep per-person drill-down views.

11. Settings includes several configuration surfaces that affect downstream behavior: ID and bill format customization, notification settings, and WhatsApp settings. These are not just UI preferences; they change how IDs, receipts, and outbound messages are generated system-wide.

12. WhatsApp integration is a major external-service boundary. The `src/app/api/whatsapp` tree includes credentials, settings, templates, sync/create, send/test, webhook, logs, queue processing, automated triggers, and DB setup. That implies asynchronous messaging, provider synchronization, inbound webhook handling, and operational logging around Meta/WhatsApp APIs.

13. `server.js` suggests there may be a custom Node server entrypoint in addition to the standard Next.js runtime, but the application architecture still centers on Next.js pages plus serverless-style route handlers.

14. For an architecture diagram, the clearest decomposition is: browser/UI pages and reusable components on one side; Next.js API routes in the middle; shared DB/auth/WhatsApp libraries underneath; and the external database plus WhatsApp provider/webhook services on the far side.

Main entry points: [`src/app`](https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app) (App shell), [`src/lib/db.js`](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/lib/db.js) (Database), [`src/app/api/whatsapp`](https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api/whatsapp) (WhatsApp API), [`src/app/api`](https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api) (Plans & reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Next.js app"]
  node_app_shell["App shell<br/>nextjs shell"]
  node_dashboard_page["Dashboard<br/>admin page<br/>[page.jsx]"]
  node_members_page["Members<br/>admin page<br/>[page.jsx]"]
  node_trainers_page["Trainers<br/>admin page<br/>[page.jsx]"]
  node_plans_page["Plans<br/>admin page<br/>[page.jsx]"]
  node_report_page["Report<br/>analytics page<br/>[page.jsx]"]
  node_settings_page["Settings<br/>config page<br/>[page.jsx]"]
  node_member_profile_page["Member profile<br/>profile page<br/>[page.jsx]"]
  node_trainer_profile_page["Trainer profile<br/>profile page<br/>[page.jsx]"]
  node_member_profile_client["Member client<br/>profile client"]
  node_trainer_profile_client["Trainer client<br/>profile client"]
end

subgraph group_api["API routes"]
  node_dashboard_api["Dashboard API<br/>stats endpoints"]
  node_member_api["Member API<br/>member CRUD"]
  node_trainer_api["Trainer API<br/>trainer CRUD"]
  node_plan_report_api["Plans & reports<br/>plan/report endpoints"]
  node_settings_api["Settings API<br/>config endpoints"]
  node_auth_api["Auth API<br/>login/logout"]
  node_whatsapp_api["WhatsApp API<br/>integration routes"]
end

subgraph group_core["Shared core"]
  node_db_lib[("Database<br/>persistence layer<br/>[db.js]")]
  node_auth_lib["Auth libs<br/>security helpers<br/>[auth.js]"]
  node_whatsapp_lib["WhatsApp lib<br/>provider helper<br/>[whatsapp.js]"]
end

subgraph group_ext["External systems"]
  node_database[("Database<br/>external db")]
  node_whatsapp_provider(("WhatsApp<br/>external provider"))
end

node_app_shell -->|"routes to"| node_dashboard_page
node_app_shell -->|"routes to"| node_members_page
node_app_shell -->|"routes to"| node_trainers_page
node_app_shell -->|"routes to"| node_plans_page
node_app_shell -->|"routes to"| node_report_page
node_app_shell -->|"routes to"| node_settings_page
node_app_shell -->|"routes to"| node_member_profile_page
node_app_shell -->|"routes to"| node_trainer_profile_page
node_member_profile_page -->|"composes"| node_member_profile_client
node_trainer_profile_page -->|"composes"| node_trainer_profile_client
node_dashboard_page -->|"loads data from"| node_dashboard_api
node_members_page -->|"loads data from"| node_member_api
node_trainers_page -->|"loads data from"| node_trainer_api
node_plans_page -->|"loads data from"| node_plan_report_api
node_report_page -->|"loads data from"| node_plan_report_api
node_settings_page -->|"loads data from"| node_settings_api
node_app_shell -->|"uses"| node_auth_api
node_auth_api -->|"uses"| node_auth_lib
node_member_api -->|"persists via"| node_db_lib
node_trainer_api -->|"persists via"| node_db_lib
node_plan_report_api -->|"persists via"| node_db_lib
node_settings_api -->|"persists via"| node_db_lib
node_dashboard_api -->|"reads from"| node_db_lib
node_whatsapp_api -->|"uses"| node_whatsapp_lib
node_whatsapp_api -->|"persists via"| node_db_lib
node_db_lib -->|"connects to"| node_database
node_whatsapp_lib -->|"connects to"| node_whatsapp_provider
node_whatsapp_api -->|"webhooks/send"| node_whatsapp_provider

click node_app_shell "https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app"
click node_dashboard_page "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/Dashboard/page.jsx"
click node_members_page "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/Members/page.jsx"
click node_trainers_page "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/Trainers/page.jsx"
click node_plans_page "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/Plans/page.jsx"
click node_report_page "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/Report/page.jsx"
click node_settings_page "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/Settings/page.jsx"
click node_member_profile_page "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/MemberProfile/page.jsx"
click node_trainer_profile_page "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/TrainerProfile/page.jsx"
click node_member_profile_client "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/MemberProfile/MemberProfileClient.jsx"
click node_trainer_profile_client "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/TrainerProfile/TrainerProfileClient.jsx"
click node_dashboard_api "https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api/dashboard_data"
click node_member_api "https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api"
click node_trainer_api "https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api"
click node_plan_report_api "https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api"
click node_settings_api "https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api"
click node_auth_api "https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api/login"
click node_whatsapp_api "https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api/whatsapp"
click node_db_lib "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/lib/db.js"
click node_auth_lib "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/lib/auth.js"
click node_whatsapp_lib "https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/lib/whatsapp.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_app_shell,node_dashboard_page,node_members_page,node_trainers_page,node_plans_page,node_report_page,node_settings_page,node_member_profile_page,node_trainer_profile_page,node_member_profile_client,node_trainer_profile_client toneBlue
class node_dashboard_api,node_member_api,node_trainer_api,node_plan_report_api,node_settings_api,node_auth_api,node_whatsapp_api toneAmber
class node_db_lib,node_auth_lib,node_whatsapp_lib toneMint
class node_database,node_whatsapp_provider toneRose
```

## Components

### Next.js app

App Router pages and shared client components for the gym admin console.

- [App shell](https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app): nextjs shell · Root layout, homepage, global styles, and middleware framing the application. · `src/app`
- [Dashboard](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/Dashboard/page.jsx): admin page · Overview page composed from dashboard cards and expiring-soon views. · `src/app/Dashboard/page.jsx`
- [Members](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/Members/page.jsx): admin page · Member management screen built from filters and list components. · `src/app/Members/page.jsx`
- [Trainers](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/Trainers/page.jsx): admin page · Trainer management screen built from filters and list components. · `src/app/Trainers/page.jsx`
- [Plans](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/Plans/page.jsx): admin page · Membership plan management screen. · `src/app/Plans/page.jsx`
- [Report](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/Report/page.jsx): analytics page · Reporting screen for stat cards, graphs, filters, and transactions. · `src/app/Report/page.jsx`
- [Settings](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/Settings/page.jsx): config page · Configuration surface for IDs, bills, notifications, and WhatsApp. · `src/app/Settings/page.jsx`
- [Member profile](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/MemberProfile/page.jsx): profile page · Dedicated member drill-down view with deep activity and plan context. · `src/app/MemberProfile/page.jsx`
- [Trainer profile](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/TrainerProfile/page.jsx): profile page · Dedicated trainer drill-down view with attendance and stats. · `src/app/TrainerProfile/page.jsx`
- [Member client](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/MemberProfile/MemberProfileClient.jsx): profile client · Client-side member profile composition and interaction layer. · `src/app/MemberProfile/MemberProfileClient.jsx`
- [Trainer client](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/app/TrainerProfile/TrainerProfileClient.jsx): profile client · Client-side trainer profile composition and interaction layer. · `src/app/TrainerProfile/TrainerProfileClient.jsx`

### API routes

Route handlers for CRUD, reporting, auth, and integrations.

- [Dashboard API](https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api/dashboard_data): stats endpoints · Dashboard data, statistics, and expiring-soon feeds. · `src/app/api/dashboard_data`
- [Member API](https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api): member CRUD · Member lifecycle, profile, attendance, balance, blacklist, and exports. · `src/app/api`
- [Trainer API](https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api): trainer CRUD · Trainer lifecycle, profile, attendance, blacklist, and exports. · `src/app/api`
- [Plans & reports](https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api): plan/report endpoints · Plan CRUD plus transaction and reporting read paths. · `src/app/api`
- [Settings API](https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api): config endpoints · ID formats, bill formats, sequence resets, and related helpers. · `src/app/api`
- [Auth API](https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api/login): login/logout · Authentication routes for session entry and exit. · `src/app/api/login`
- [WhatsApp API](https://github.com/urbanzi-solution/gym-app-version2/tree/master/src/app/api/whatsapp): integration routes · Credentials, templates, send/test, queue, webhook, and automation handling. · `src/app/api/whatsapp`

### Shared core

Persistence, auth, and integration libraries used across the app.

- [Database](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/lib/db.js): persistence layer · Shared DB access boundary for all business data and configuration. · `src/lib/db.js`
- [Auth libs](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/lib/auth.js): security helpers · JWT, auth, and encryption utilities supporting protected routes. · `src/lib/auth.js`
- [WhatsApp lib](https://github.com/urbanzi-solution/gym-app-version2/blob/master/src/lib/whatsapp.js): provider helper · Shared WhatsApp integration helpers used by the API layer. · `src/lib/whatsapp.js`

### External systems

Database and third-party provider boundaries.

- **Database**: external db · Primary persistence store for members, trainers, plans, transactions, settings, and logs.
- **WhatsApp**: external provider · External messaging platform, templates, and webhook source.

## Connections

- App shell → Dashboard: routes to · App Router pages are served under the shared shell.
- App shell → Members: routes to · Member management is part of the main app surface.
- App shell → Trainers: routes to · Trainer management is part of the main app surface.
- App shell → Plans: routes to · Plan management is part of the main app surface.
- App shell → Report: routes to · Reporting is rendered within the shared shell.
- App shell → Settings: routes to · Settings is rendered within the shared shell.
- App shell → Member profile: routes to · Member profile is a dedicated route.
- App shell → Trainer profile: routes to · Trainer profile is a dedicated route.
- Member profile → Member client: composes · The page delegates interactive profile UI to the client component.
- Trainer profile → Trainer client: composes · The page delegates interactive profile UI to the client component.
- Dashboard → Dashboard API: loads data from · Dashboard views are driven by summary endpoints.
- Members → Member API: loads data from · Member pages consume list and mutation endpoints.
- Trainers → Trainer API: loads data from · Trainer pages consume list and mutation endpoints.
- Plans → Plans & reports: loads data from · Plans page uses plan CRUD routes.
- Report → Plans & reports: loads data from · Reports use transaction and analytics endpoints.
- Settings → Settings API: loads data from · Settings UI reads and writes configuration endpoints.
- App shell → Auth API: uses · Login and logout routes support the protected app shell.
- Auth API → Auth libs: uses · Auth routes rely on shared authentication helpers.
- Member API → Database: persists via · Member workflows read and write through the DB boundary.
- Trainer API → Database: persists via · Trainer workflows read and write through the DB boundary.
- Plans & reports → Database: persists via · Plans, transactions, and reports are database-backed.
- Settings API → Database: persists via · Formats and sequences are stored centrally.
- Dashboard API → Database: reads from · Dashboard metrics are assembled from stored records.
- WhatsApp API → WhatsApp lib: uses · WhatsApp routes share integration helpers.
- WhatsApp API → Database: persists via · Credentials, logs, templates, and queue state are stored in the database.
- Database → Database: connects to · Shared persistence boundary points at the primary database.
- WhatsApp lib → WhatsApp: connects to · Integration helpers communicate with the external provider.
- WhatsApp API → WhatsApp: webhooks/send · Routes handle outbound sends and inbound webhook traffic.
