Skip to main content

Architecture Overview

medOS-ultra is structured as a microservice backend behind an API gateway, a React 19 SPA in the browser, and a Supabase projection layer that acts as the read-model cache for the frontend.

NATS
Service bus
Moleculer
Framework
MongoDB
Primary store
PostgreSQL
E-Form store
Supabase
Read model
IPFS + S3
File store

Request flow​

Frontend (React 19 / Vite)
   │ REST / HTTPS
   ▼
ALB or nginx
   │
   ▼
API Gateway (Moleculer-web, :3001)
   │ JWT validation, routing
   ▼
NATS message bus
   │ request / reply + pub/sub
   ▼
Microservices (NestJS + Moleculer)
   │
   ├─▶ MongoDB (primary write store)
   ├─▶ PostgreSQL (E-Form service only)
   ├─▶ Supabase edge functions (projection)
   │     └─▶ Supabase read model tables
   │             └─▶ Frontend (realtime subscription)
   ├─▶ IPFS / S3 (filestore)
   └─▶ External systems (FHIR / HL7 / SMART)
Topology

Service Mesh

All NestJS services register with Moleculer and communicate via NATS. The Gateway is the single ingress.

Gateway :3001NATSMongoSupabaseIPFS
Ingress

Gateway

Routes every request by service scope. Handles JWT verification and Moleculer action invocation.

ever-api-gatewaymoleculer-web:3001
Identity

Auth (AAA)

JWT + Keycloak optional. Role-based access with RBAC cached at the gateway.

ever-api-aaaJWTKeycloak
Transport

NATS

Request / reply + fan-out events. Every microservice is a Moleculer node.

natsmoleculer 0.14pub/sub
State

MongoDB

Primary store for clinical, admin, medication, financial records.

mongoosereplica setchange streams
Projection

Supabase

Read-model tables + edge functions for realtime subscriptions.

PostgreSQLRLSRealtimeDeno functions
Files

IPFS + S3

The filestore service supports both backends transparently.

IPFSS3hash verify

Key architectural rules​

  1. Never write directly to Supabase read-model tables from the frontend — go through the backend API.
  2. Market-pack parity — application code must be identical across regions; only seeds, locale, and insurance-rate tables differ.
  3. Bilingual seed data — local language + English for every seed.
  4. All env vars in Docker Compose must be parameterized (no hardcoded URLs).
  5. Use FHIR for external exchange; use HL7v2 for legacy integration with instruments and ADT feeds.

See also​