Architecture Overview

import { Badge } from ‘@astrojs/starlight/components’;

Architecture Overview

End-to-end system design, multi-tenancy model, and request lifecycle.

Last reviewed: 2026-07-18

---

System Diagram

graph TB
    subgraph Clients["🌐 Clients"]
        Browser["Browser (React 18 + Radix + Framer Motion)"]
        PWA["PWA (Installed)"]
        WhatsApp["WhatsApp (Patient)"]
        Slack["Slack (Internal Ops)"]
    end

    subgraph Railway["🚂 Railway Platform"]
        FE["Frontend Service<br/>Vite + Caddy<br/>:80 → dist/*"]
        BE["Backend Service<br/>Node.js 22+ (TypeScript)<br/>:3000 → /api/* /webhooks/*"]
        SlackBot["Slack Bot Service<br/>Node.js"]
    end

    subgraph Supabase_["🗄️ Supabase PostgreSQL"]
        PG[("50-Table Schema<br/>+ RLS Policies")]
        Auth["JWKS Endpoint<br/>ES256 P-256 Keys"]
    end

    subgraph Redis_["⚡ Redis (Railway)"]
        BQ["BullMQ Queues"]
        Cache["Cache + Distributed Locks"]
    end

    subgraph External["🔌 External Integrations"]
        MH["Hacienda DTE (El Salvador)"]
        MetaCloud["Meta WhatsApp Cloud API"]
        Anthropic["Anthropic Claude Haiku"]
        LS["LemonSqueezy"]
        Resend["Resend Email"]
    end

    Browser -->|HTTPS| FE
    PWA -->|HTTPS| FE
    FE -->|HTTPS /api/*| BE

    WhatsApp -->|Inbound Webhook| MetaCloud
    MetaCloud -->|POST /webhooks/whatsapp| BE

    Slack -->|Events / Actions| SlackBot
    SlackBot -.->|Updates| BE

    BE --> PG
    BE --> BQ
    BE --> Cache
    BE -->|DTE Signing & Invoices| MH
    BE -->|NLU & Copilot Stream| Anthropic
    BE -->|Payment Webhooks| LS
    BE -->|Transactional Email| Resend

    BQ -.->|Background Jobs| BE

    style PWA fill:#0369a1,stroke:#38bdf8,color:#ffffff
    style WA fill:#0369a1,stroke:#38bdf8,color:#ffffff
    style Slack fill:#0369a1,stroke:#38bdf8,color:#ffffff
    style API fill:#1e293b,stroke:#0284c7,color:#ffffff
    style Workers fill:#1e293b,stroke:#0284c7,color:#ffffff
    style DB fill:#0f172a,stroke:#0284c7,color:#ffffff
    style Auth fill:#0f172a,stroke:#0284c7,color:#ffffff
    style Redis fill:#0f172a,stroke:#0284c7,color:#ffffff
    style MH fill:#1e293b,stroke:#0284c7,color:#ffffff
    style Claude fill:#1e293b,stroke:#0284c7,color:#ffffff
    style LS fill:#1e293b,stroke:#0284c7,color:#ffffff
    style Resend fill:#1e293b,stroke:#0284c7,color:#ffffff
    style BE fill:#007AFF26,stroke:#007AFF,stroke-width:2px
    style FE fill:#007AFF26,stroke:#007AFF,stroke-width:2px

Core Design Principles

Multi-Tenancy Architecture

ClinicFlow implements a strict 3-tier multi-tenancy model to guarantee complete tenant isolation across all 50 database tables:

1. Cryptographic Claims: Every JWT access token contains an asymmetric ES256-signed clinicId claim (userToken.ts).
2. Request-Scoped Database Client (req.db): Protected endpoints attach a Supabase client initialized with the caller’s JWT. All database queries execute under public.jwt_clinic_id().
3. Database Row-Level Security (RLS): PostgreSQL RLS policies enforce clinic_id = public.jwt_clinic_id() at the SQL engine level. Private SQL helper functions (private.request_is_active(), private.request_is_admin(), private.request_is_system()) evaluate active tenant state and role privileges.

Multi-Tenancy Rule

Every database query against a clinic-owned table must execute under req.db or explicitly filter .eq('clinic_id', req.user.clinicId). req.user.clinicId comes from the verified ES256 JWT — never from request input parameters.

Two Supabase client instances support this pattern:

Client Instance	Key Type	RLS Enforcement	Primary Purpose
req.db / supabase	ES256 User JWT / Anon	Enforced at SQL layer	All tenant user requests and API queries.
supabaseAdmin	Service Role Key	Bypassed (private.request_is_system())	System cron jobs, BullMQ workers, and superadmin bootstrap tasks.

Subscription & Feature Gating

Protected routes enforce a composable middleware chain:

Request → authenticateToken → requireActiveSubscription
         → [requireAdmin] → [checkDoctorLimit | requireDentalFeature | requirePlan] → handler

Tip

requireActiveSubscription performs a live database check on every request to immediately intercept suspended clinics or deactivated accounts without waiting for session token expiration.

---

Tech Stack & Versioning

Technology	Version	Purpose
Node.js	>= 22.0.0	High-performance backend runtime (tsx loader execution)
Express	4.21.2	Backend HTTP server framework
TypeScript	5.7.3	Complete backend and frontend type safety
React	18.3.1	Frontend application UI engine
Vite	6.4.3	Frontend build pipeline & manual chunking
PostgreSQL / Supabase	15+	Multi-tenant database with 50 tables, RLS, and custom RPCs
Tailwind CSS	3.4.17	Styling system using custom OKLCH tokens
BullMQ / ioredis	5.41.5 / 5.6.0	Redis-backed distributed job queues & locks
@anthropic-ai/sdk	0.37.0	Claude Haiku NLU chatbot & Copilot streaming engine
@phosphor-icons/react	2.1.7	Unified vector icon primitive system
Vitest	3.0.7	Test framework across backend and frontend suites