# fitsiomaxtech-os/osfitsiomax architecture

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

- Interactive diagram: https://gitdiagram.com/fitsiomaxtech-os/osfitsiomax
- Repository: https://github.com/fitsiomaxtech-os/osfitsiomax

## Overview

#### Purpose and Entrypoints
FitsioMax is a multi-branch physiotherapy/fitness operations platform: CRM and lead pipeline, appointments/sessions, clinical boards, HR, finance, inventory, marketing, and a patient portal. The browser client starts at `frontend/src/index.js` and `frontend/src/App.js`; its principal application pages include `frontend/src/pages/CRMPage.jsx` and `frontend/src/pages/PatientPortalPage.jsx`. The Python API entrypoint is `backend/server.py`.

#### Client Application
The frontend is a React single-page application, with feature boards rendered as component-level modules rather than a separate service per domain. API interaction is centralized in `frontend/src/lib/api.js`, while client-side role interpretation and workflow helpers live in `frontend/src/lib/roles.js` and `frontend/src/lib/session.js`. Major UI domains are represented by:
- CRM/presales: `frontend/src/components/PreSalesCRM.jsx`, `frontend/src/components/BusinessLeadsDashboard.jsx`
- Branch operations: `frontend/src/components/branch/BranchManagementBoard.jsx`, `frontend/src/components/branch/BranchDetailPage.jsx`
- Clinical scheduling: `frontend/src/components/PhysioBoard.jsx`, `frontend/src/components/ConsultationsBoard.jsx`

#### API Versioning and Domain Routing
The backend exposes a versioned router boundary: legacy/API generations reside in `backend/routers/v1.py`, `backend/routers/v2.py`, and the broad v3 router set. V3 is organized by business capability, allowing frontend boards to invoke bounded APIs while sharing a single process and database layer. Core route groups include leads (`backend/routers/v3_leads.py`), appointments (`backend/routers/v3_appointments.py`), sessions (`backend/routers/v3_session_assign.py`), branch administration (`backend/routers/v3_branch_admin.py`), and finance (`backend/routers/v3_finance.py`).

#### Identity, Authorization, and Role-Scoped Workflows
Authentication and authorization are backend concerns implemented around `backend/security.py` and dependency injection in `backend/deps.py`, with account/profile endpoints in `backend/routers/v3_auth.py` and `backend/routers/v3_me.py`. Role-specific views and APIs separate responsibilities such as head physio, branch admin, HR, and public super-admin provisioning. This is reflected in `backend/routers/v3_head_physio.py`, `backend/routers/v3_hr.py`, and `backend/routers/v3_public_super_admin.py`; the frontend consumes this boundary through role-aware boards.

#### Operational Data Flow
A primary flow is lead acquisition and qualification through staged CRM work, then conversion into appointments, sessions, and patient-facing care records. Lead state, mapping, and pipeline logic are concentrated in `backend/routers/v3_leads.py`, `backend/routers/v3_stages.py`, and `backend/stage_utils.py`. Scheduling and treatment assignment cross into `backend/routers/v3_appointments.py` and `backend/routers/v3_session_assign.py`. Branch-level dashboards aggregate those operational records alongside finance, staff, store, and clock data through routes such as `backend/routers/v3_dashboard.py`, `backend/routers/v3_clock.py`, and `backend/routers/v3_inventory.py`.

#### Persistence and Integrations
The application uses a document-oriented database, evidenced by BSON database backups under `db_backup/test_database/` and database access/index modules at `backend/database.py` and `backend/indexes.py`. Seed data is managed by `backend/seed.py`. Google Sheets is an explicit external integration with connection/token/mapping data represented in backups and APIs in `backend/routers/v3_google_sheets.py` and `backend/routers/v3_sheets.py`. Email-related flows, including password reset, are bounded by `backend/email_utils.py` and `backend/routers/v3_password_reset.py`.

#### Delivery Surface
Frontend build customization uses CRACO (`frontend/craco.config.js`), while Python dependencies are defined in `backend/requirements.txt`. Deployment automation is defined in `.github/workflows/deploy.yml`. The repository also contains database backup artifacts and restoration markers, indicating that deployment/restore state is operationally significant rather than purely local development metadata.

Main entry points: [`backend/routers/v2.py`](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v2.py) (Versioned route boundary), [`backend/database.py`](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/database.py) (Document database), [`frontend/src/index.js`](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/index.js) (SPA entry & shell), [`backend/routers/v3_leads.py`](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_leads.py) (Leads & pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React client"]
  node_client_entry["SPA entry &amp; shell<br/>React application<br/>[index.js]"]
  node_crm_page["CRM &amp; portal pages<br/>application pages<br/>[CRMPage.jsx]"]
  node_crm_boards["Presales CRM boards<br/>feature components<br/>[PreSalesCRM.jsx]"]
  node_branch_boards["Branch operations boards<br/>feature components"]
  node_clinical_boards["Clinical scheduling boards<br/>feature components<br/>[PhysioBoard.jsx]"]
  node_api_client["API client<br/>client gateway<br/>[api.js]"]
  node_role_workflows["Role workflows<br/>client authorization<br/>[roles.js]"]
end

subgraph group_api["Python API"]
  node_api_entry["API server<br/>Python entrypoint<br/>[server.py]"]
  node_versioned_routes["Versioned route boundary<br/>API generations<br/>[v2.py]"]
  node_identity["Identity &amp; authorization<br/>security dependencies<br/>[security.py]"]
  node_leads_pipeline["Leads &amp; pipeline<br/>v3 routes<br/>[v3_leads.py]"]
  node_stages["Pipeline stages<br/>workflow logic<br/>[v3_stages.py]"]
  node_scheduling["Appointments &amp; sessions<br/>v3 routes<br/>[v3_appointments.py]"]
  node_branch_admin["Branch administration<br/>v3 routes<br/>[v3_branch_admin.py]"]
  node_operations_dashboard["Operational dashboards<br/>v3 routes<br/>[v3_dashboard.py]"]
  node_finance["Finance<br/>v3 routes<br/>[v3_finance.py]"]
  node_email{{"Email &amp; password reset<br/>external messaging<br/>[email_utils.py]"}}
end

subgraph group_data["Data &amp; integrations"]
  node_document_db[("Document database<br/>persistence<br/>[database.py]")]
  node_db_indexes["Database indexes<br/>persistence optimization<br/>[indexes.py]"]
  node_sheets{{"Google Sheets<br/>external integration"}}
end

subgraph group_delivery["Delivery"]
  node_deployment["Deployment workflow<br/>CI/CD<br/>[deploy.yml]"]
end

node_client_entry -->|"renders"| node_crm_page
node_crm_page -->|"hosts"| node_crm_boards
node_client_entry -->|"renders"| node_branch_boards
node_client_entry -->|"renders"| node_clinical_boards
node_client_entry -->|"applies roles"| node_role_workflows
node_crm_boards -->|"uses"| node_api_client
node_branch_boards -->|"uses"| node_api_client
node_clinical_boards -->|"uses"| node_api_client
node_api_client -->|"HTTP API"| node_api_entry
node_api_entry -->|"mounts"| node_versioned_routes
node_versioned_routes -->|"authorizes"| node_identity
node_versioned_routes -->|"routes"| node_leads_pipeline
node_leads_pipeline -->|"manages"| node_stages
node_leads_pipeline -->|"converts leads"| node_scheduling
node_versioned_routes -->|"routes"| node_branch_admin
node_versioned_routes -->|"routes"| node_operations_dashboard
node_versioned_routes -->|"routes"| node_finance
node_identity -->|"accounts"| node_document_db
node_leads_pipeline -->|"persists"| node_document_db
node_scheduling -->|"persists care records"| node_document_db
node_branch_admin -->|"persists"| node_document_db
node_operations_dashboard -->|"aggregates"| node_document_db
node_finance -->|"persists"| node_document_db
node_document_db -->|"indexed by"| node_db_indexes
node_versioned_routes -->|"syncs"| node_sheets
node_identity -->|"password recovery"| node_email
node_deployment -.->|"delivers"| node_client_entry
node_deployment -.->|"deploys"| node_api_entry

click node_client_entry "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/index.js"
click node_crm_page "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/pages/CRMPage.jsx"
click node_crm_boards "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/components/PreSalesCRM.jsx"
click node_branch_boards "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/components/branch/BranchManagementBoard.jsx"
click node_clinical_boards "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/components/PhysioBoard.jsx"
click node_api_client "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/lib/api.js"
click node_role_workflows "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/lib/roles.js"
click node_api_entry "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/server.py"
click node_versioned_routes "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v2.py"
click node_identity "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/security.py"
click node_leads_pipeline "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_leads.py"
click node_stages "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_stages.py"
click node_scheduling "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_appointments.py"
click node_branch_admin "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_branch_admin.py"
click node_operations_dashboard "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_dashboard.py"
click node_finance "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_finance.py"
click node_document_db "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/database.py"
click node_db_indexes "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/indexes.py"
click node_sheets "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_google_sheets.py"
click node_email "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/email_utils.py"
click node_deployment "https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/.github/workflows/deploy.yml"

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_client_entry,node_crm_page,node_crm_boards,node_branch_boards,node_clinical_boards,node_api_client,node_role_workflows toneBlue
class node_api_entry,node_versioned_routes,node_identity,node_leads_pipeline,node_stages,node_scheduling,node_branch_admin,node_operations_dashboard,node_finance,node_email toneAmber
class node_document_db,node_db_indexes,node_sheets toneMint
class node_deployment toneRose
```

## Components

### React client

- [SPA entry & shell](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/index.js): React application · `frontend/src/index.js`
- [CRM & portal pages](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/pages/CRMPage.jsx): application pages · `frontend/src/pages/CRMPage.jsx`
- [Presales CRM boards](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/components/PreSalesCRM.jsx): feature components · `frontend/src/components/PreSalesCRM.jsx`
- [Branch operations boards](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/components/branch/BranchManagementBoard.jsx): feature components · `frontend/src/components/branch/BranchManagementBoard.jsx`
- [Clinical scheduling boards](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/components/PhysioBoard.jsx): feature components · `frontend/src/components/PhysioBoard.jsx`
- [API client](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/lib/api.js): client gateway · `frontend/src/lib/api.js`
- [Role workflows](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/frontend/src/lib/roles.js): client authorization · `frontend/src/lib/roles.js`

### Python API

- [API server](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/server.py): Python entrypoint · `backend/server.py`
- [Versioned route boundary](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v2.py): API generations · `backend/routers/v2.py`
- [Identity & authorization](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/security.py): security dependencies · `backend/security.py`
- [Leads & pipeline](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_leads.py): v3 routes · `backend/routers/v3_leads.py`
- [Pipeline stages](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_stages.py): workflow logic · `backend/routers/v3_stages.py`
- [Appointments & sessions](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_appointments.py): v3 routes · `backend/routers/v3_appointments.py`
- [Branch administration](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_branch_admin.py): v3 routes · `backend/routers/v3_branch_admin.py`
- [Operational dashboards](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_dashboard.py): v3 routes · `backend/routers/v3_dashboard.py`
- [Finance](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_finance.py): v3 routes · `backend/routers/v3_finance.py`
- [Email & password reset](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/email_utils.py): external messaging · `backend/email_utils.py`

### Data & integrations

- [Document database](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/database.py): persistence · `backend/database.py`
- [Database indexes](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/indexes.py): persistence optimization · `backend/indexes.py`
- [Google Sheets](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/backend/routers/v3_google_sheets.py): external integration · `backend/routers/v3_google_sheets.py`

### Delivery

- [Deployment workflow](https://github.com/fitsiomaxtech-os/osfitsiomax/blob/main/.github/workflows/deploy.yml): CI/CD · `.github/workflows/deploy.yml`

## Connections

- SPA entry & shell → CRM & portal pages: renders
- CRM & portal pages → Presales CRM boards: hosts
- SPA entry & shell → Branch operations boards: renders
- SPA entry & shell → Clinical scheduling boards: renders
- SPA entry & shell → Role workflows: applies roles
- Presales CRM boards → API client: uses
- Branch operations boards → API client: uses
- Clinical scheduling boards → API client: uses
- API client → API server: HTTP API
- API server → Versioned route boundary: mounts
- Versioned route boundary → Identity & authorization: authorizes
- Versioned route boundary → Leads & pipeline: routes
- Leads & pipeline → Pipeline stages: manages
- Leads & pipeline → Appointments & sessions: converts leads
- Versioned route boundary → Branch administration: routes
- Versioned route boundary → Operational dashboards: routes
- Versioned route boundary → Finance: routes
- Identity & authorization → Document database: accounts
- Leads & pipeline → Document database: persists
- Appointments & sessions → Document database: persists care records
- Branch administration → Document database: persists
- Operational dashboards → Document database: aggregates
- Finance → Document database: persists
- Document database → Database indexes: indexed by
- Versioned route boundary → Google Sheets: syncs
- Identity & authorization → Email & password reset: password recovery
- Deployment workflow → SPA entry & shell: delivers
- Deployment workflow → API server: deploys