How bomussa/love works
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: api-unified.js Client services · App.jsx App shell · schema.sql Supabase DB · status.js API v1
Components 18
Browser client
React frontend and client-side workflow orchestration
- App shell · Main client orchestrator that routes users into role-specific workflow screens
frontend/src/App.jsx - Patient flow · Login, exam selection, QR scan, queue entry, and status tracking
frontend/src/components/PatientPage.jsx - Doctor flow · Clinic dashboard and queue completion controls for clinical staff
frontend/src/components/DoctorDashboard.jsx - Admin flow · Admin dashboards, queue monitors, diagnostics, repair, and notifications
frontend/src/components/AdminDashboardV2.jsx - Display flow · Public wallboard and queue display surfaces
frontend/src/components/DisplayPage.jsx - Client services · Auth, queue, routing, realtime sync, persistence, and resilience modules
frontend/src/lib/api-unified.js - Resilience layer · Offline-first behavior, cache, safe mode, and auto-repair support
frontend/src/lib/offline-first-system.js - Realtime bus · 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 · Primary browser and server data access path into Supabase
frontend/src/lib/supabase-client.js - Supabase DB · Canonical tables, migrations, schema snapshots, and RLS-backed persistence
supabase/schema.sql - Edge Functions · Server-side Supabase functions for login, queue, status, reports, and health
supabase/functions/login/index.ts - API v1 · Serverless `/api/v1` compatibility surface for queue, routes, reports, stats, and events
pages/api/v1/status.js - API adapters · Shared API helpers, routing, reports, and storage adapters behind the HTTP layer
pages/api/lib/helpers.js - Legacy API · Older integration paths and compatibility adapters kept for alternate clients
lib/local-api.js
Operations
Deployment, diagnostics, and recovery tooling
- Vercel deploy · Frontend deployment and build/runtime configuration for production delivery
frontend/vercel.json - Infra tools · Cloudflare, tunnels, systemd, docker, and recovery scripts for alternate hosting
deploy/cloudflared/config.yml - Diagnostics · Smoke tests, schema analysis, audits, and repair scripts that validate the contract
diagnostics/project-analysis.json - Test harness · Playwright, smoke, and integration checks for the workflow and API surfaces
frontend/tests/smoke.spec.ts
Connections 22
- 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