How bomussa/love-api works
1. Overall shape
- This repo is a backend for the MMC-MMS medical queue/examination system.
- It is split into two main runtime surfaces: a Vercel-hosted HTTP API under api/, and Supabase-hosted Edge Functions under supabase/functions/.
- Supabase is the intended source of truth for data and business-state enforcement; the Vercel API layer acts as the external façade and compatibility layer.
2. Primary external entrypoints
- api/health.js, api/v1.js, api/v1/status.js, api/v1/health.js, and api/maintenance.js are the public HTTP endpoints surfaced through Vercel.
- The README indicates /api/v1 is the main API base, with /api/health for global health and /api/v1/status plus /api/v1/health for runtime and compatibility checks.
- vercel.json and ecosystem.config.js suggest deployment/runtime configuration is managed for serverless hosting and process execution.
3. Core API boundary
- api/v1.js is the main router for queue and clinic workflows.
- Supporting files in api/lib/ provide helper functions and storage abstractions used by those endpoints.
- This layer appears to normalize requests, route to the right domain operation, and preserve backward compatibility with older API shapes.
4. Shared server-side domain library
- The lib/ directory contains the core domain and integration modules used by both API routes and tests.
- Important subsystems include authentication (admin-auth.js), database access (db.js, supabase-db.js), queue rules (queue.ts, queue-canonical-contract.js), storage (unified-storage.js, storage.js), routing (routing.js), request handling, and logging.
- There is also explicit compatibility plumbing in files like api-adapter.js, supabase-api.js, local-api.js, and enhanced-api.js, which indicates the backend supports multiple runtime or API shapes during migration.
5. Queue workflow is the main business system
- The queue lifecycle is a first-class domain: entry, status, calling the next patient, and clinic progression.
- The queue is enforced through both shared library logic and Supabase Edge Functions such as queue-enter, queue-status, queue-call, call-next-patient, and queue-engine.
- This suggests a split between request-facing endpoints and a more authoritative queue engine that enforces atomicity and status transitions.
6. Patient, doctor, and admin journeys
- The README’s user journeys map directly onto backend subsystems: patient login and PIN verification, doctor login and “next patient” actions, and admin monitoring/reporting.
- Supabase functions like login, patient-login, admin-login, and admin-session-verify cover identity/session flows.
- Admin operations are further supported by database and policy management functions such as db-check, db-tables-manager, and db-policies-manager.
7. Supabase as data and policy layer
- The supabase/migrations/ directory contains the canonical schema and policy evolution for the system.
- Migration names show emphasis on queue canonicalization, lifecycle enforcement, atomic inserts, RLS hardening, notifications, doctors, and system settings.
- The architecture relies on database migrations and RLS policies to enforce correctness and security, not just application code.
8. Compatibility and legacy coexistence
- The repo contains legacy/ migrations and supabase/ plus top-level migrations/ artifacts, showing a transition from older queue structures to a unified runtime.
- Docs and scripts mention schema contracts, route contracts, and queue canonicalization, indicating the system is actively maintaining backward compatibility while converging on a single model.
- Files such as api/v1.js.bak, lib/*.bak, and legacy/README.md reinforce that older paths still exist during the migration period.
9. Operational and diagnostics layer
- Health/status endpoints, maintenance endpoints, and scripts like inspect_supabase_full.js, check-tables.js, and check-admins-schema.js support operational inspection.
- BACKEND_OPERATIONS_GUIDE.md, VERCEL_ENV_SETUP.md, and docs under docs/ define runbooks, environment setup, and contract audits.
- This repo treats observability and recovery as part of the backend architecture, not an afterthought.
10. Automation, validation, and safety controls
- GitHub Actions workflows enforce CI, deployment, migration guards, and secret scanning.
- Test suites in tests/, lib/*.test.ts, and supabase/functions/*_test.ts validate contracts such as CORS, queue behavior, admin auth, and module import health.
- Scripts like check-queue-contract.js, check-schema-contract.js, and check-migration-safety.js show that schema/API compatibility is guarded by automated checks.
11. Data flow at a high level
- Client requests enter through Vercel API routes or directly through Supabase Edge Functions, depending on the endpoint family.
- Those requests are validated, authenticated, and normalized by shared libraries, then committed to Supabase-backed state via database access or RPC-style operations.
- Live queue state is then exposed back through status/health/report endpoints and, where relevant, realtime/operational endpoints in Supabase.
12. Key architecture boundaries to draw
- Boundary 1: public HTTP surface vs internal shared logic.
- Boundary 2: Vercel API compatibility layer vs Supabase Edge Functions queue runtime.
- Boundary 3: application code vs database-enforced rules/migrations.
- Boundary 4: modern canonical queue model vs legacy compatibility paths.
13. Practical diagram takeaway
- The system is not just “an API”; it is a queue-centric backend with a dual runtime, where Supabase owns persistence and policy, Vercel exposes the public API, and shared libraries coordinate authentication, routing, and compatibility during an ongoing migration.
Main entry points: v1.js API v1 · index.ts Queue Engine · queue.ts Queue Core · db.js DB Core
Components 24
Vercel API
Public HTTP surface and compatibility routes.
- Health · Global Vercel health check.
api/health.js - API v1 · Main Vercel-facing router for queue and clinic workflows.
api/v1.js - V1 Health · Versioned health endpoint for compatibility checks.
api/v1/health.js - V1 Status · Versioned runtime status endpoint.
api/v1/status.js - Maintenance · Operational and recovery endpoint surfaced by Vercel.
api/maintenance.js - API Helpers · Vercel route normalization and utility helpers.
api/lib/helpers.js - API Storage · API-layer storage abstraction used by route handlers.
api/lib/storage.js
Shared Library
Core domain, routing, auth, storage, and compatibility logic reused across runtimes.
- Admin Auth · Admin login, verification, and session checks.
lib/admin-auth.js - Routing · Shared request routing and dispatch logic.
lib/routing.js - Queue Core · Queue lifecycle, transitions, and business rules.
lib/queue.ts - Queue Contract · Canonical queue schema and compatibility rules.
lib/queue-canonical-contract.js - DB Core · Shared database access and query layer.
lib/db.js - Supabase DB · Supabase-specific database integration layer.
lib/supabase-db.js - Unified Storage · Shared storage facade across runtime variants.
lib/unified-storage.js - API Adapter · Bridges modern, local, and Supabase API shapes during migration.
lib/api-adapter.js
Supabase Runtime
Edge Functions that own queue and session workflows.
- API Router · Supabase Edge Function router for request dispatch and auth.
supabase/functions/api-router/index.ts - Queue Engine · Authoritative queue workflow and atomic state enforcement.
supabase/functions/queue-engine/index.ts - Queue Enter · Patient queue entry flow.
supabase/functions/queue-enter/index.ts - Queue Status · Queue status lookup and visibility.
supabase/functions/queue-status/index.ts - Queue Call · Next-patient calling workflow.
supabase/functions/queue-call/index.ts - Login · Shared login/session entrypoint for patients and staff.
supabase/functions/login/index.ts - Admin Login · Admin authentication entrypoint.
supabase/functions/admin-login/index.ts
Supabase Schema
Migrations and policy enforcement that define canonical state.
- Queue Canon · Canonical queue model and lifecycle enforcement.
supabase/migrations/20260316090000_canonicalize_queues.sql - RLS Harden · Policy hardening and public-write restriction for canonical state.
supabase/migrations/20260519090000_harden_rls_and_block_public_write_policies.sql
Connections 26
- Health → DB Core: checks · Health probes underlying backend availability.
- API v1 → API Helpers: normalizes · Routes and reshapes incoming requests.
- API v1 → Routing: dispatches via · Main API router delegates to shared routing logic.
- API v1 → API Adapter: compatibility · Preserves legacy and alternate API shapes.
- API v1 → Queue Core: serves · Exposes queue workflows to clients.
- V1 Health → API v1: mirrors · Versioned health endpoint is part of the v1 surface.
- V1 Status → API v1: mirrors · Versioned status endpoint is part of the v1 surface.
- Maintenance → DB Core: operates on · Maintenance endpoint inspects or repairs backend state.
- API Helpers → API Storage: uses · Helpers coordinate route storage needs.
- Routing → Admin Auth: authenticates · Routing layer applies admin/session checks where needed.
- Routing → Queue Core: routes to · Dispatches queue-related operations.
- Queue Core → Queue Contract: conforms to · Business rules follow canonical queue contract.
- Queue Core → DB Core: persists via · Queue transitions are committed through database access.
- DB Core → Supabase DB: backs onto · Database layer is specialized for Supabase runtime.
- Unified Storage → API Storage: adapts · Unifies storage behavior across API/runtime variants.
- API Router → Admin Auth: verifies · Edge router authenticates privileged requests.
- API Router → Queue Engine: delegates · Routes queue operations to authoritative engine.
- Queue Enter → Queue Engine: invokes · Queue entry flows are enforced by the engine.
- Queue Status → Queue Engine: reads · Status views are derived from queue engine state.
- Queue Call → Queue Engine: advances · Next-patient calls are executed by the engine.
- Login → Admin Auth: shares auth · Login flows reuse shared authentication logic.
- Admin Login → Admin Auth: shares auth · Admin login is backed by the shared auth layer.
- Queue Engine → Queue Canon: depends on · Engine behavior matches canonicalized schema and lifecycle rules.
- Queue Canon → RLS Harden: protected by · Canonical queue model is enforced under hardened policies.
- RLS Harden → Supabase DB: enforced in · RLS and schema policy are applied at the database layer.
- API Adapter → API Router: bridges · Compatibility layer can bridge toward Supabase edge routing.