# bomussa/love-api architecture

> Architecture diagram of the GitHub repository bomussa/love-api, 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-api
- Repository: https://github.com/bomussa/love-api

## Overview

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: [`api/v1.js`](https://github.com/bomussa/love-api/blob/master/api/v1.js) (API v1), [`supabase/functions/queue-engine/index.ts`](https://github.com/bomussa/love-api/blob/master/supabase/functions/queue-engine/index.ts) (Queue Engine), [`lib/queue.ts`](https://github.com/bomussa/love-api/blob/master/lib/queue.ts) (Queue Core), [`lib/db.js`](https://github.com/bomussa/love-api/blob/master/lib/db.js) (DB Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vercel_api["Vercel API"]
  node_api_health["Health<br/>http endpoint<br/>[health.js]"]
  node_api_v1["API v1<br/>http router<br/>[v1.js]"]
  node_api_v1_health["V1 Health<br/>compat endpoint<br/>[health.js]"]
  node_api_v1_status["V1 Status<br/>status endpoint<br/>[status.js]"]
  node_api_maintenance["Maintenance<br/>ops endpoint<br/>[maintenance.js]"]
  node_api_helpers["API Helpers<br/>helper module<br/>[helpers.js]"]
  node_api_storage[("API Storage<br/>storage adapter<br/>[storage.js]")]
end

subgraph group_shared_lib["Shared Library"]
  node_admin_auth["Admin Auth<br/>auth module<br/>[admin-auth.js]"]
  node_routing["Routing<br/>router core<br/>[routing.js]"]
  node_queue_core{{"Queue Core<br/>domain logic<br/>[queue.ts]"}}
  node_queue_contract["Queue Contract<br/>compat contract"]
  node_db_core[("DB Core<br/>database access<br/>[db.js]")]
  node_supabase_db[("Supabase DB<br/>supabase access<br/>[supabase-db.js]")]
  node_unified_storage[("Unified Storage<br/>storage facade<br/>[unified-storage.js]")]
  node_api_adapter["API Adapter<br/>compat layer<br/>[api-adapter.js]"]
end

subgraph group_supabase_runtime["Supabase Runtime"]
  node_supabase_api_router["API Router<br/>edge router<br/>[index.ts]"]
  node_queue_engine{{"Queue Engine<br/>edge worker<br/>[index.ts]"}}
  node_queue_enter_fn["Queue Enter<br/>edge function<br/>[index.ts]"]
  node_queue_status_fn["Queue Status<br/>edge function<br/>[index.ts]"]
  node_queue_call_fn["Queue Call<br/>edge function<br/>[index.ts]"]
  node_login_fn["Login<br/>edge function<br/>[index.ts]"]
  node_admin_login_fn["Admin Login<br/>edge function<br/>[index.ts]"]
end

subgraph group_supabase_schema["Supabase Schema"]
  node_supabase_migrate_queue["Queue Canon<br/>migration"]
  node_supabase_migrate_rls["RLS Harden<br/>migration"]
end

node_api_health -->|"checks"| node_db_core
node_api_v1 -->|"normalizes"| node_api_helpers
node_api_v1 -->|"dispatches via"| node_routing
node_api_v1 -->|"compatibility"| node_api_adapter
node_api_v1 -->|"serves"| node_queue_core
node_api_v1_health -->|"mirrors"| node_api_v1
node_api_v1_status -->|"mirrors"| node_api_v1
node_api_maintenance -->|"operates on"| node_db_core
node_api_helpers -->|"uses"| node_api_storage
node_routing -->|"authenticates"| node_admin_auth
node_routing -->|"routes to"| node_queue_core
node_queue_core -->|"conforms to"| node_queue_contract
node_queue_core -->|"persists via"| node_db_core
node_db_core -->|"backs onto"| node_supabase_db
node_unified_storage -->|"adapts"| node_api_storage
node_supabase_api_router -->|"verifies"| node_admin_auth
node_supabase_api_router -->|"delegates"| node_queue_engine
node_queue_enter_fn -->|"invokes"| node_queue_engine
node_queue_status_fn -->|"reads"| node_queue_engine
node_queue_call_fn -->|"advances"| node_queue_engine
node_login_fn -->|"shares auth"| node_admin_auth
node_admin_login_fn -->|"shares auth"| node_admin_auth
node_queue_engine -->|"depends on"| node_supabase_migrate_queue
node_supabase_migrate_queue -->|"protected by"| node_supabase_migrate_rls
node_supabase_migrate_rls -->|"enforced in"| node_supabase_db
node_api_adapter -->|"bridges"| node_supabase_api_router

click node_api_health "https://github.com/bomussa/love-api/blob/master/api/health.js"
click node_api_v1 "https://github.com/bomussa/love-api/blob/master/api/v1.js"
click node_api_v1_health "https://github.com/bomussa/love-api/blob/master/api/v1/health.js"
click node_api_v1_status "https://github.com/bomussa/love-api/blob/master/api/v1/status.js"
click node_api_maintenance "https://github.com/bomussa/love-api/blob/master/api/maintenance.js"
click node_api_helpers "https://github.com/bomussa/love-api/blob/master/api/lib/helpers.js"
click node_api_storage "https://github.com/bomussa/love-api/blob/master/api/lib/storage.js"
click node_admin_auth "https://github.com/bomussa/love-api/blob/master/lib/admin-auth.js"
click node_routing "https://github.com/bomussa/love-api/blob/master/lib/routing.js"
click node_queue_core "https://github.com/bomussa/love-api/blob/master/lib/queue.ts"
click node_queue_contract "https://github.com/bomussa/love-api/blob/master/lib/queue-canonical-contract.js"
click node_db_core "https://github.com/bomussa/love-api/blob/master/lib/db.js"
click node_supabase_db "https://github.com/bomussa/love-api/blob/master/lib/supabase-db.js"
click node_unified_storage "https://github.com/bomussa/love-api/blob/master/lib/unified-storage.js"
click node_api_adapter "https://github.com/bomussa/love-api/blob/master/lib/api-adapter.js"
click node_supabase_api_router "https://github.com/bomussa/love-api/blob/master/supabase/functions/api-router/index.ts"
click node_queue_engine "https://github.com/bomussa/love-api/blob/master/supabase/functions/queue-engine/index.ts"
click node_queue_enter_fn "https://github.com/bomussa/love-api/blob/master/supabase/functions/queue-enter/index.ts"
click node_queue_status_fn "https://github.com/bomussa/love-api/blob/master/supabase/functions/queue-status/index.ts"
click node_queue_call_fn "https://github.com/bomussa/love-api/blob/master/supabase/functions/queue-call/index.ts"
click node_login_fn "https://github.com/bomussa/love-api/blob/master/supabase/functions/login/index.ts"
click node_admin_login_fn "https://github.com/bomussa/love-api/blob/master/supabase/functions/admin-login/index.ts"
click node_supabase_migrate_queue "https://github.com/bomussa/love-api/blob/master/supabase/migrations/20260316090000_canonicalize_queues.sql"
click node_supabase_migrate_rls "https://github.com/bomussa/love-api/blob/master/supabase/migrations/20260519090000_harden_rls_and_block_public_write_policies.sql"

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_api_health,node_api_v1,node_api_v1_health,node_api_v1_status,node_api_maintenance,node_api_helpers,node_api_storage toneBlue
class node_admin_auth,node_routing,node_queue_core,node_queue_contract,node_db_core,node_supabase_db,node_unified_storage,node_api_adapter toneAmber
class node_supabase_api_router,node_queue_engine,node_queue_enter_fn,node_queue_status_fn,node_queue_call_fn,node_login_fn,node_admin_login_fn toneMint
class node_supabase_migrate_queue,node_supabase_migrate_rls toneRose
```

## Components

### Vercel API

Public HTTP surface and compatibility routes.

- [Health](https://github.com/bomussa/love-api/blob/master/api/health.js): http endpoint · Global Vercel health check. · `api/health.js`
- [API v1](https://github.com/bomussa/love-api/blob/master/api/v1.js): http router · Main Vercel-facing router for queue and clinic workflows. · `api/v1.js`
- [V1 Health](https://github.com/bomussa/love-api/blob/master/api/v1/health.js): compat endpoint · Versioned health endpoint for compatibility checks. · `api/v1/health.js`
- [V1 Status](https://github.com/bomussa/love-api/blob/master/api/v1/status.js): status endpoint · Versioned runtime status endpoint. · `api/v1/status.js`
- [Maintenance](https://github.com/bomussa/love-api/blob/master/api/maintenance.js): ops endpoint · Operational and recovery endpoint surfaced by Vercel. · `api/maintenance.js`
- [API Helpers](https://github.com/bomussa/love-api/blob/master/api/lib/helpers.js): helper module · Vercel route normalization and utility helpers. · `api/lib/helpers.js`
- [API Storage](https://github.com/bomussa/love-api/blob/master/api/lib/storage.js): storage adapter · 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](https://github.com/bomussa/love-api/blob/master/lib/admin-auth.js): auth module · Admin login, verification, and session checks. · `lib/admin-auth.js`
- [Routing](https://github.com/bomussa/love-api/blob/master/lib/routing.js): router core · Shared request routing and dispatch logic. · `lib/routing.js`
- [Queue Core](https://github.com/bomussa/love-api/blob/master/lib/queue.ts): domain logic · Queue lifecycle, transitions, and business rules. · `lib/queue.ts`
- [Queue Contract](https://github.com/bomussa/love-api/blob/master/lib/queue-canonical-contract.js): compat contract · Canonical queue schema and compatibility rules. · `lib/queue-canonical-contract.js`
- [DB Core](https://github.com/bomussa/love-api/blob/master/lib/db.js): database access · Shared database access and query layer. · `lib/db.js`
- [Supabase DB](https://github.com/bomussa/love-api/blob/master/lib/supabase-db.js): supabase access · Supabase-specific database integration layer. · `lib/supabase-db.js`
- [Unified Storage](https://github.com/bomussa/love-api/blob/master/lib/unified-storage.js): storage facade · Shared storage facade across runtime variants. · `lib/unified-storage.js`
- [API Adapter](https://github.com/bomussa/love-api/blob/master/lib/api-adapter.js): compat layer · 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](https://github.com/bomussa/love-api/blob/master/supabase/functions/api-router/index.ts): edge router · Supabase Edge Function router for request dispatch and auth. · `supabase/functions/api-router/index.ts`
- [Queue Engine](https://github.com/bomussa/love-api/blob/master/supabase/functions/queue-engine/index.ts): edge worker · Authoritative queue workflow and atomic state enforcement. · `supabase/functions/queue-engine/index.ts`
- [Queue Enter](https://github.com/bomussa/love-api/blob/master/supabase/functions/queue-enter/index.ts): edge function · Patient queue entry flow. · `supabase/functions/queue-enter/index.ts`
- [Queue Status](https://github.com/bomussa/love-api/blob/master/supabase/functions/queue-status/index.ts): edge function · Queue status lookup and visibility. · `supabase/functions/queue-status/index.ts`
- [Queue Call](https://github.com/bomussa/love-api/blob/master/supabase/functions/queue-call/index.ts): edge function · Next-patient calling workflow. · `supabase/functions/queue-call/index.ts`
- [Login](https://github.com/bomussa/love-api/blob/master/supabase/functions/login/index.ts): edge function · Shared login/session entrypoint for patients and staff. · `supabase/functions/login/index.ts`
- [Admin Login](https://github.com/bomussa/love-api/blob/master/supabase/functions/admin-login/index.ts): edge function · Admin authentication entrypoint. · `supabase/functions/admin-login/index.ts`

### Supabase Schema

Migrations and policy enforcement that define canonical state.

- [Queue Canon](https://github.com/bomussa/love-api/blob/master/supabase/migrations/20260316090000_canonicalize_queues.sql): migration · Canonical queue model and lifecycle enforcement. · `supabase/migrations/20260316090000_canonicalize_queues.sql`
- [RLS Harden](https://github.com/bomussa/love-api/blob/master/supabase/migrations/20260519090000_harden_rls_and_block_public_write_policies.sql): migration · Policy hardening and public-write restriction for canonical state. · `supabase/migrations/20260519090000_harden_rls_and_block_public_write_policies.sql`

## Connections

- 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.
