# bomussa/love architecture

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

- Interactive diagram: https://gitdiagram.com/bomussa/love
- Repository: https://github.com/bomussa/love

## Overview

1. **What this repo is**
   This repository is a Vite + React frontend for the MMC-MMS workflow system, deployed to Vercel and backed by Supabase. The live application is centered in `frontend/src/` and uses Supabase as the source of truth for operational data.

2. **Primary runtime boundary**
   The architecture is split between:
   - the **browser client**: React UI, session logic, queue monitoring, offline/resilience helpers
   - the **data/services layer**: Supabase tables, RLS, and Edge Functions
   - the **HTTP compatibility layer**: `/api/v1` endpoints and related adapters for older or alternate integrations

3. **UI orchestration**
   `frontend/src/App.jsx` is the main orchestration point. It routes users into role-specific screens for patients, doctors, clinic staff, and admins. The UI is not a simple single-screen app; it is a multi-journey workflow app with distinct operational views.

4. **Role-based frontends**
   The major presentation subsystems live under `frontend/src/components/`:
   - patient flow: login, exam selection, QR scan, queue entry, status tracking
   - doctor flow: clinic dashboard, queue control, completion actions
   - admin/clinic flow: dashboards, queue monitors, repair/diagnostics panels, notifications
   - display flow: public or wallboard-style queue display screens

5. **Client service layer**
   The browser does most of its business logic through `frontend/src/lib/`. The important boundary here is that these modules are not just helpers; they are the application’s service layer:
   - `api-unified.js` and `supabase-client.js` are the live data access path
   - `auth-service.js` handles authentication/session behavior
   - `queueManager.js`, `routingManager.js`, `realtime-sync-manager.js`, and `persistent-connection.js` coordinate queue state, route progression, and live updates
   - `offline-first-system.js`, `cache-manager.js`, and self-healing modules provide resilience when connectivity is unstable

6. **Canonical data source**
   Supabase is the authoritative backend. The repository includes:
   - schema and migration history in `supabase/migrations/`
   - SQL schema snapshots in `supabase/schema.sql`
   - Edge Functions in `supabase/functions/`
   - helper code in `functions/lib/`
   This is the real persistence boundary for queue, routing, auth, and reporting data.

7. **HTTP/API contract**
   The app also exposes a `/api/v1` contract through serverless routes in `pages/api/v1/` and supporting libs in `pages/api/lib/`. These endpoints cover status, queue actions, patient login, routing, events streaming, reports, and stats. The frontend treats this as a compatibility surface, not the primary domain model.

8. **Core workflow data flow**
   The main operational flow is:
   patient login → exam selection → queue entry → route creation → live queue tracking → station completion.  
   Doctors and clinic staff then call the next patient and mark completion, moving queue records through the canonical states `waiting`, `called`, and `completed`.

9. **Realtime and notifications**
   Live updates are a first-class subsystem. The repo contains SSE/event-stream support, realtime sync managers, broadcasters, and notification modules. This means queue changes propagate to dashboards and display screens without relying only on manual refreshes.

10. **Legacy and compatibility boundaries**
   The repo still contains legacy surfaces and fallback code paths:
   - `local-api.js`, `api-adapter.js`, and some root-level `lib/` and `src/` trees support older integration patterns
   - the readme explicitly says PIN-based clinic control is legacy and not part of the active contract
   For an architecture diagram, these should be shown as fallback/legacy edges, not as the main system path.

11. **Deployment and infrastructure**
   The primary production deployment is Vercel for the frontend, with Supabase for data/services. The repo also includes Cloudflare, tunnel, and systemd/docker artifacts under `deploy/`, `infra/`, and root scripts for alternate hosting, self-hosting, and operational recovery. These are important deployment boundaries but not the main runtime logic.

12. **Operational tooling**
   There is a substantial ops/testing layer: diagnostics, smoke tests, Playwright, CI workflows, schema analysis, and repair scripts. These tools exist to validate the integrity of the frontend-to-Supabase contract and to support recovery, but they are outside the product runtime path.

13. **What to emphasize in a diagram**
   The clearest diagram should show:
   - browser-based role-specific React UI
   - client service layer wrapping auth, queue, routing, realtime, and resilience
   - Supabase as the system of record
   - `/api/v1` and Edge Function compatibility surfaces
   - realtime event flow back into dashboards/displays
   - legacy fallback paths and deployment tooling as side branches, not the core path

Main entry points: [`frontend/src/lib/api-unified.js`](https://github.com/bomussa/love/blob/main/frontend/src/lib/api-unified.js) (Client services), [`frontend/src/App.jsx`](https://github.com/bomussa/love/blob/main/frontend/src/App.jsx) (App shell), [`supabase/schema.sql`](https://github.com/bomussa/love/blob/main/supabase/schema.sql) (Supabase DB), [`pages/api/v1/status.js`](https://github.com/bomussa/love/blob/main/pages/api/v1/status.js) (API v1)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser client"]
  node_app["App shell<br/>react-router shell<br/>[App.jsx]"]
  node_patient_ui["Patient flow<br/>react screens<br/>[PatientPage.jsx]"]
  node_doctor_ui["Doctor flow<br/>react screens"]
  node_admin_ui["Admin flow<br/>react screens"]
  node_display_ui["Display flow<br/>react screens<br/>[DisplayPage.jsx]"]
  node_client_services[("Client services<br/>workflow services<br/>[api-unified.js]")]
  node_offline_repair{{"Resilience layer<br/>offline/self-heal"}}
  node_realtime_bus(("Realtime bus<br/>event sync<br/>[event-bus.js]"))
end

subgraph group_backend["Data and API"]
  node_supabase_api[("Supabase access<br/>data client<br/>[supabase-client.js]")]
  node_supabase_db[("Supabase DB<br/>system of record<br/>[schema.sql]")]
  node_edge_functions["Edge Functions<br/>supabase functions<br/>[index.ts]"]
  node_api_v1["API v1<br/>compat http api<br/>[status.js]"]
  node_api_lib[("API adapters<br/>server lib<br/>[helpers.js]")]
  node_legacy_api["Legacy API<br/>fallback surface<br/>[local-api.js]"]
end

subgraph group_ops["Operations"]
  node_vercel_deploy["Vercel deploy<br/>hosting config<br/>[vercel.json]"]
  node_infra_tools["Infra tools<br/>ops tooling<br/>[config.yml]"]
  node_diagnostics["Diagnostics<br/>ops tooling"]
  node_test_tooling["Test harness<br/>tests<br/>[smoke.spec.ts]"]
end

node_app -->|"routes"| node_patient_ui
node_app -->|"routes"| node_doctor_ui
node_app -->|"routes"| node_admin_ui
node_app -->|"routes"| node_display_ui
node_patient_ui -->|"uses"| node_client_services
node_doctor_ui -->|"uses"| node_client_services
node_admin_ui -->|"uses"| node_client_services
node_display_ui -->|"subscribes"| node_realtime_bus
node_client_services -->|"reads/writes"| node_supabase_api
node_client_services -->|"publishes"| node_realtime_bus
node_offline_repair -->|"wraps"| node_client_services
node_supabase_api -->|"persists"| node_supabase_db
node_edge_functions -->|"executes"| node_supabase_db
node_api_v1 -->|"delegates"| node_api_lib
node_api_lib -->|"bridges"| node_supabase_api
node_legacy_api -.->|"fallback to"| node_api_lib
node_api_v1 -->|"serves"| node_supabase_db
node_vercel_deploy -->|"hosts"| node_app
node_infra_tools -.->|"supports"| node_vercel_deploy
node_diagnostics -.->|"validates"| node_supabase_db
node_test_tooling -.->|"verifies"| node_api_v1
node_test_tooling -.->|"verifies"| node_client_services

click node_app "https://github.com/bomussa/love/blob/main/frontend/src/App.jsx"
click node_patient_ui "https://github.com/bomussa/love/blob/main/frontend/src/components/PatientPage.jsx"
click node_doctor_ui "https://github.com/bomussa/love/blob/main/frontend/src/components/DoctorDashboard.jsx"
click node_admin_ui "https://github.com/bomussa/love/blob/main/frontend/src/components/AdminDashboardV2.jsx"
click node_display_ui "https://github.com/bomussa/love/blob/main/frontend/src/components/DisplayPage.jsx"
click node_client_services "https://github.com/bomussa/love/blob/main/frontend/src/lib/api-unified.js"
click node_offline_repair "https://github.com/bomussa/love/blob/main/frontend/src/lib/offline-first-system.js"
click node_realtime_bus "https://github.com/bomussa/love/blob/main/frontend/src/core/event-bus.js"
click node_supabase_api "https://github.com/bomussa/love/blob/main/frontend/src/lib/supabase-client.js"
click node_supabase_db "https://github.com/bomussa/love/blob/main/supabase/schema.sql"
click node_edge_functions "https://github.com/bomussa/love/blob/main/supabase/functions/login/index.ts"
click node_api_v1 "https://github.com/bomussa/love/blob/main/pages/api/v1/status.js"
click node_api_lib "https://github.com/bomussa/love/blob/main/pages/api/lib/helpers.js"
click node_legacy_api "https://github.com/bomussa/love/blob/main/lib/local-api.js"
click node_vercel_deploy "https://github.com/bomussa/love/blob/main/frontend/vercel.json"
click node_infra_tools "https://github.com/bomussa/love/blob/main/deploy/cloudflared/config.yml"
click node_diagnostics "https://github.com/bomussa/love/blob/main/diagnostics/project-analysis.json"
click node_test_tooling "https://github.com/bomussa/love/blob/main/frontend/tests/smoke.spec.ts"

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,node_patient_ui,node_doctor_ui,node_admin_ui,node_display_ui,node_client_services,node_offline_repair,node_realtime_bus toneBlue
class node_supabase_api,node_supabase_db,node_edge_functions,node_api_v1,node_api_lib,node_legacy_api toneAmber
class node_vercel_deploy,node_infra_tools,node_diagnostics,node_test_tooling toneMint
```

## Components

### Browser client

React frontend and client-side workflow orchestration

- [App shell](https://github.com/bomussa/love/blob/main/frontend/src/App.jsx): react-router shell · Main client orchestrator that routes users into role-specific workflow screens · `frontend/src/App.jsx`
- [Patient flow](https://github.com/bomussa/love/blob/main/frontend/src/components/PatientPage.jsx): react screens · Login, exam selection, QR scan, queue entry, and status tracking · `frontend/src/components/PatientPage.jsx`
- [Doctor flow](https://github.com/bomussa/love/blob/main/frontend/src/components/DoctorDashboard.jsx): react screens · Clinic dashboard and queue completion controls for clinical staff · `frontend/src/components/DoctorDashboard.jsx`
- [Admin flow](https://github.com/bomussa/love/blob/main/frontend/src/components/AdminDashboardV2.jsx): react screens · Admin dashboards, queue monitors, diagnostics, repair, and notifications · `frontend/src/components/AdminDashboardV2.jsx`
- [Display flow](https://github.com/bomussa/love/blob/main/frontend/src/components/DisplayPage.jsx): react screens · Public wallboard and queue display surfaces · `frontend/src/components/DisplayPage.jsx`
- [Client services](https://github.com/bomussa/love/blob/main/frontend/src/lib/api-unified.js): workflow services · Auth, queue, routing, realtime sync, persistence, and resilience modules · `frontend/src/lib/api-unified.js`
- [Resilience layer](https://github.com/bomussa/love/blob/main/frontend/src/lib/offline-first-system.js): offline/self-heal · Offline-first behavior, cache, safe mode, and auto-repair support · `frontend/src/lib/offline-first-system.js`
- [Realtime bus](https://github.com/bomussa/love/blob/main/frontend/src/core/event-bus.js): event sync · Event bus and broadcaster that push live queue changes to screens · `frontend/src/core/event-bus.js`

### Data and API

Supabase persistence plus HTTP compatibility surfaces

- [Supabase access](https://github.com/bomussa/love/blob/main/frontend/src/lib/supabase-client.js): data client · Primary browser and server data access path into Supabase · `frontend/src/lib/supabase-client.js`
- [Supabase DB](https://github.com/bomussa/love/blob/main/supabase/schema.sql): system of record · Canonical tables, migrations, schema snapshots, and RLS-backed persistence · `supabase/schema.sql`
- [Edge Functions](https://github.com/bomussa/love/blob/main/supabase/functions/login/index.ts): supabase functions · Server-side Supabase functions for login, queue, status, reports, and health · `supabase/functions/login/index.ts`
- [API v1](https://github.com/bomussa/love/blob/main/pages/api/v1/status.js): compat http api · Serverless `/api/v1` compatibility surface for queue, routes, reports, stats, and events · `pages/api/v1/status.js`
- [API adapters](https://github.com/bomussa/love/blob/main/pages/api/lib/helpers.js): server lib · Shared API helpers, routing, reports, and storage adapters behind the HTTP layer · `pages/api/lib/helpers.js`
- [Legacy API](https://github.com/bomussa/love/blob/main/lib/local-api.js): fallback surface · Older integration paths and compatibility adapters kept for alternate clients · `lib/local-api.js`

### Operations

Deployment, diagnostics, and recovery tooling

- [Vercel deploy](https://github.com/bomussa/love/blob/main/frontend/vercel.json): hosting config · Frontend deployment and build/runtime configuration for production delivery · `frontend/vercel.json`
- [Infra tools](https://github.com/bomussa/love/blob/main/deploy/cloudflared/config.yml): ops tooling · Cloudflare, tunnels, systemd, docker, and recovery scripts for alternate hosting · `deploy/cloudflared/config.yml`
- [Diagnostics](https://github.com/bomussa/love/blob/main/diagnostics/project-analysis.json): ops tooling · Smoke tests, schema analysis, audits, and repair scripts that validate the contract · `diagnostics/project-analysis.json`
- [Test harness](https://github.com/bomussa/love/blob/main/frontend/tests/smoke.spec.ts): tests · Playwright, smoke, and integration checks for the workflow and API surfaces · `frontend/tests/smoke.spec.ts`

## Connections

- App shell → Patient flow: routes · App shell sends users into the patient journey
- App shell → Doctor flow: routes · App shell sends clinicians into the doctor workflow
- App shell → Admin flow: routes · App shell opens admin and operations views
- App shell → Display flow: routes · App shell opens wallboard/display screens
- Patient flow → Client services: uses · Patient screens call shared workflow services
- Doctor flow → Client services: uses · Doctor controls use the shared client service layer
- Admin flow → Client services: uses · Admin panels depend on the same orchestration services
- Display flow → Realtime bus: subscribes · Display surfaces react to live events and queue updates
- Client services → Supabase access: reads/writes · Client services access canonical data through Supabase clients
- Client services → Realtime bus: publishes · Workflow services emit live events for dashboards and displays
- Resilience layer → Client services: wraps · Resilience modules protect and recover the client workflow layer
- Supabase access → Supabase DB: persists · Supabase client reads and writes the system of record
- Edge Functions → Supabase DB: executes · Edge functions operate against the same canonical database
- API v1 → API adapters: delegates · Versioned HTTP endpoints use shared API helpers and adapters
- API adapters → Supabase access: bridges · API helpers bridge HTTP requests to Supabase-backed data access
- Legacy API → API adapters: fallback to · Legacy compatibility paths reuse or mirror the newer API helpers
- API v1 → Supabase DB: serves · Compatibility endpoints ultimately operate on the canonical data store
- Vercel deploy → App shell: hosts · Production frontend delivery is centered on Vercel
- Infra tools → Vercel deploy: supports · Alternate hosting and recovery tooling support deployment operations
- Diagnostics → Supabase DB: validates · Diagnostics inspect schema, migrations, and runtime contract health
- Test harness → API v1: verifies · Tests exercise the HTTP compatibility surface and workflow endpoints
- Test harness → Client services: verifies · Tests also cover browser-side workflow logic and resilience behavior
