medOS Administration

Internal scope: ever-api-administration  ·  Port: 4002

The largest service in the platform. Administration owns system-wide configuration, master data, and the read-model-facing events & webhook plane. It is where reference catalogs (countries, clinics, departments, blood types, bed types), patient demographics, scheduling/calendar configuration, and inpatient/blood-bank setup all live — plus the outbound webhook dispatcher and the clinical-event emitter that feed the read model and external subscribers. Roughly 211 modules are mounted here, making it the broadest surface in the NestJS + Moleculer mesh.

211

Modules

4002

Default port

NATS

Transport

FHIR R4

Webhook envelope

Responsibilities

• Master data & reference catalogs — countries, nationalities, religions, occupations, languages, titles, genders, marital status, specialties, and the facility tree (hospital, building, floor, clinic, sub-clinic, department, room).
• Patient demographics & profile — patient records, categories, notes and note templates, contact/address data, audit logs, and profile-tab config.
• Inpatient & bed management — admission, bed, bed type, bed requests, and bed/admission audit trails.
• Blood bank — donors, donor evaluation/stock, component separation, transactions, and blood-type bags.
• Scheduling — appointments, doctor schedules and rooms, slot templates, calendars, holidays, blackout dates, and queue-priority settings.
• Clinical & nursing config — care plans, care teams, chief-complaint templates, focus lists, assessments, problems, conditions, and risk profiles.
• Events & integration — the clinical-event emitter (cdsEventEmitter) and the outbound webhook dispatcher (JSON & FHIR Bundle), plus FHIR subscription management.

Major modules

Module	Purpose
patient, patientCategory, patientNote, patientAuditLog	Patient demographics, categorization, notes/templates, and audit trail
hospital, building, buildingFloor, clinic, subClinic, department, room	The facility / location tree used across the platform
country, nationality, religion, occupation, gender, maritalStatus, title	Reference catalogs / master data
admission, bed, bedType, bedRequest, bedAuditLog, admissionLog	Inpatient bed and admission setup with audit logging
bloodDonor, bloodDonorStock, bloodComponentSeparator, bloodTransaction, bloodTypeBag	Blood-bank donor, inventory, and component pipeline
appointment, doctorSchedule, doctorRoom, slotTemplate, calendarAppointment, holiday, departmentBlackoutDate	Scheduling, calendars, and availability windows
queueSetting, queuePrioritySetting, clinicQueuePrioritySetting	Queue and priority configuration
carePlan, careTeam, chiefComplaintTemplate, focusList, problems, condition	Care-coordination and clinical-config building blocks
riskProfile, riskProfileGroup, riskProfileTopic, riskAssessment, riskManagementControl	Risk-management framework
cdsEventEmitter	Emits clinical/domain events onto the bus for read-model projection and CDS
webhookSubscription	Webhook subscription CRUD + outbound dispatcher (see below)
fhirSubscription, fhirIntegration	FHIR R4 subscription registry and integration glue
transferRequest, patientTransfer, referrer	Movement, transfer, and referral configuration

Webhook dispatcher

The webhookSubscription module ships a production-grade outbound dispatcher. Each subscription chooses a payload format — a plain JSON envelope or a FHIR R4 Bundle (payloadFormat: 'fhir'), where Moleculer event prefixes are mapped to FHIR resource types and transformed locally before send.

Delivery is hardened with:

• HMAC-signed payloads so receivers can verify authenticity.
• Stable idempotency key computed once per logical payload and reused across every retry attempt.
• Exponential backoff with jitter — retryable only on network/timeout, 429, and 5xx; 4xx is treated as permanent.
• Dead-letter handling — exhausted deliveries are marked in the delivery log and remain replayable (they carry payload, target URL, subscription, and event).

 Domain change (NestJS/Moleculer)
        │  emits event
        ▼
 cdsEventEmitter ──► NATS event bus ──► encounter-orchestrator (read model)
        │
        ▼
 webhookDispatcher
   ├─ resolve matching subscriptions
   ├─ build envelope (JSON | FHIR R4 Bundle)
   ├─ sign (HMAC) + stable idempotency key
   ├─ POST ──► external subscriber
   └─ on failure: backoff + retry ─► dead-letter (replayable)

Integration notes

• Domain events emitted here flow over NATS and are projected into the Supabase read model by the encounter orchestrator; see Architecture.
• The FHIR webhook envelope mirrors the transformers used by the public FHIR API; see FHIR Integration.
• This service is the master-data backbone for the rest of the mesh; see the Backend Services Overview for the full service map.

Master data CRUDWebhook dispatcher (JSON + FHIR)HMAC signing + retry + dead-letterFHIR subscriptions

Related catalog items

• CP-3 … CP-12 — Admin Panel / master-data modules
• BB-1 … BB-4 — Blood Bank
• IPD-3, IPD-4 — Bed & Ward configuration
• WH-1 … WH-8 — Webhooks & Events