Data Flow

End-to-end write flow

sequenceDiagram
  participant U as Clinician (UI)
  participant G as API Gateway
  participant S as Microservice
  participant M as MongoDB
  participant E as Supabase Edge Fn
  participant P as Postgres read model
  U->>G: REST write (order, vitals, …)
  G->>S: NATS request
  S->>M: persist (source of truth)
  S-->>E: emit domain event
  E->>P: upsert read model
  P-->>U: realtime push (sub-second)

medOS-ultra separates the write path (operational, strongly consistent, Mongo) from the read path (projected, eventually consistent, Supabase).

Write path

1. Frontend POSTs to the gateway.
2. Gateway authenticates the JWT and forwards the Moleculer action.
3. The owning microservice validates, writes to MongoDB, emits a Moleculer event.
4. The event is consumed by any interested service (e.g. foundation, messaging, public-api).

Projection path

1. A change stream / Moleculer event fans out to the projector.
2. A Supabase edge function (fhir-subscription-matcher, family-feed-projector, etc.) writes to the read-model table.
3. Frontend subscriptions receive the realtime patch.

Read path

1. Frontend calls a Supabase read endpoint (RLS-gated) — fast, cached, realtime.
2. For write-through queries or complex joins, frontend calls the API gateway.

Event conventions

Event	Emitter	Purpose
patient.registered	administration	Triggers welcome SMS, chart init
encounter.created	clinical	Kicks off worklist + FHIR subscription
medication.administered	medication	Updates MAR + Kardex read models
lab.result.ready	diagnostic	Notifies clinician via Socket.IO
claim.submitted	financial	Pushes to NHSO / PhilHealth / Kaigo