fitsiomaxtech-os/osfitsiomax

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.