SERVICE_REFERENCE

Service Reference

API Gateway (port 58080)

The unified entry point for all BRAINSAIT services. Proxies to 23 backends + 19 Pulse agents + HF models + Security.

Endpoints

Method	Path	Backend	Description
GET	/health	—	Gateway health + available services
GET	/routes	—	API discovery with examples
*	/fhir/{path}	localhost:52773	FHIR R4 proxy (synthetic CapabilityStatement)
*	/linc/{agent}	Local Python	19 Pulse AI agents
*	/hf/{action}	Local Python	HF models status + chat
GET	/security/health	Local Python	Security module status
*	/patients/{*rest}	HNH Worker	Patient records
*	/hospitals/{*rest}	HNH Worker	Hospital directory
*	/encounters/{*rest}	HNH Worker	Clinical encounters
*	/facilities/{*rest}	HNH Worker	Facility data
*	/eligibility/{*rest}	NPHIES Worker	Insurance eligibility
*	/claims/{*rest}	NPHIES Worker	Claim submission + tracking
*	/prior-auth/{*rest}	NPHIES Worker	Prior authorization
*	/submit/{*rest}	nphies-submit	NPHIES submission
*	/comm-req/{*rest}	NPHIES Worker	Communication requests
*	/voice/{*rest}	BASMA Worker	Voice AI
*	/tts/{*rest}	BASMA Worker	Text-to-speech
*	/voices/{*rest}	BASMA Worker	Voice profiles
*	/translate/{*rest}	BASMA Worker	Translation
*	/cds/{*rest}	GIVC Worker	Clinical decision support
*	/academy/{*rest}	GIVC Worker	Academy platform
*	/courses/{*rest}	GIVC Worker	Course catalog
*	/certification/{*rest}	GIVC Worker	Certifications
*	/billing/{*rest}	SBS Worker	Billing system
*	/coverage/{*rest}	SBS Worker	Insurance coverage
*	/subscriptions/{*rest}	SBS Worker	Subscriptions
*	/oracle/{*rest}	Oracle Bridge	EBS portal bridge
*	/ehr/{*rest}	Oracle Bridge	EHR data access
*	/scanner/{action}	Local CLI	Oracle scanner automation

Pulse Agents (19)

#	Agent	Endpoint	FHIR Resource	Description
1	Summary	/linc/summary	DocumentReference	Role-tailored patient summary
2	Prior Auth	/linc/prior-auth	CommunicationRequest	Insurance coverage copilot
3	Gaps in Care	/linc/gaps-in-care	CarePlan	Preventive screening gaps
4	Medication Safety	/linc/medication-safety	MedicationDispense	Drug interaction + allergy checks
5	Care Plan	/linc/care-plan	CarePlan	AI-powered care pathways
6	Clinical Trials	/linc/clinical-trials	ResearchStudy	Trial eligibility matching
7	Readmission Risk	/linc/readmission-risk	RiskAssessment	30-day readmission risk
8	Triage	/linc/triage	Encounter	Acuity assessment + routing
9	Imaging Followup	/linc/imaging-followup	ImagingStudy	Pending imaging results
10	Lab Explainer	/linc/lab-explainer	Observation	Plain-language lab results
11	NL Query	/linc/nl-query	Parameters	Natural language FHIR queries
12	SDOH Referral	/linc/sdoh-referral	ServiceRequest	Community resource matching
13	Chat	/hf/chat	Parameters	Clinical chat AI
14	HF Models	/hf/models	Parameters	HuggingFace model status
15	Predict Readmission	/linc/predict-readmission	RiskAssessment	30-day risk, mitigations, confidence
16	Predict PA Denial	/linc/predict-pa-denial	RiskAssessment	Pre-submission denial probability
17	Predict ED Util	/linc/predict-ed-util	RiskAssessment	7d + 30d ED visit forecast
18	Predict Interaction	/linc/predict-interaction	RiskAssessment	4 drug-drug interactions + severity
19	Predict No-Show	/linc/predict-no-show	RiskAssessment	No-show probability + interventions

Usage Examples

# Discover all routes
curl http://localhost:58080/routes | jq .

# Pulse agents list
curl http://localhost:58080/linc/ | jq .

# Patient summary via Pulse
curl "http://localhost:58080/linc/summary?patient=P-5842" | jq .

# Chat with AI
curl "http://localhost:58080/hf/chat?q=chest%20pain%20protocol" | jq .

# HF model status
curl http://localhost:58080/hf/models | jq .

# FHIR metadata
curl http://localhost:58080/fhir/metadata | jq .

# Predictive: readmission risk
curl "http://localhost:58080/linc/predict-readmission?patientId=P001" | jq .

# Predictive: drug interaction check
curl "http://localhost:58080/linc/predict-interaction?patientId=P005&medications=metformin,lisinopril,warfarin,atorvastatin" | jq .

# Security health
curl http://localhost:58080/security/health | jq .

---

Ecosystem Supervisor (port 58773)

Monitors all containers and workers, manages circuit breakers, triggers auto-recovery, orchestrates workflows.

Endpoints

Method	Path	Description
GET,POST	/	Service info + endpoint map
GET,POST	/health	Full health dashboard
GET,POST	/containers	Docker container status
GET,POST	/workers	Worker API probe results
GET,POST	/circuits	Circuit breaker states
GET	/cache/{key}	Get Redis cached value
POST	/cache/clear	Clear Redis cache
GET,POST	/probe	Trigger manual probe cycle
GET,POST	/recover/{container}	Restart a specific container
GET,POST	/recover/all	Restart all unhealthy containers
GET,POST	/workflow	List available workflows
GET,POST	/workflow/homecare/{patient}	Run homecare workflow

Monitored Containers (13)

Container	Image	Port	Status
iris-unified	intersystems/irishealth-community:2026.1	52773	✅
postgres-brainsait	postgres:15-alpine	5432	✅
redis-ecosystem	redis:7-alpine	6379	✅
cloudflare-tunnel	cloudflare/cloudflared	—	✅
brainsait-grafana	grafana/grafana:latest	3000	✅
brainsait-browser-agent	brainsait-browser-agent	3001	✅
coolify	coolify:4.1.0	8000	✅
coolify-proxy	traefik:v3.6	80,443	✅
coolify-realtime	coolify-realtime:1.0.15	6001-6002	✅
coolify-db	postgres:15-alpine	—	✅
coolify-redis	redis:7-alpine	—	✅
coolify-sentinel	sentinel:0.0.21	—	✅
github-runner	ghcr.io/actions/actions-runner	—	✅

Probe Cycle (automatic, every 30s)

1. Check all 13 Docker containers (running status)
2. Probe all 8 worker APIs (HTTP reachability + latency)
3. Update circuit breakers (open on failure, close on success)
4. Check PostgreSQL and Redis connectivity
5. Refresh health cache
6. Evaluate alert rules
7. Auto-recover unhealthy containers (max 3 per cycle)

Circuit Breaker States

State	Meaning	Behavior
closed	Normal	Requests pass through
open	Too many failures	Requests blocked, timer starts
half-open	Probing recovery	Single test request allowed

---

Live Dashboard (port 58081)

Real-time browser dashboard with auto-refreshing health data via Server-Sent Events (SSE).

Method	Path	Description
GET	/	Full HTML dashboard page
GET	/events	SSE stream (polls supervisor every 5s)

Displays container status (color-coded), worker API reachability + latency, circuit breaker states, database connectivity, and summary stats.

---

Webhook Receiver (port 58082)

Receives external webhook events and persists them to PostgreSQL with Write-Ahead Log (WAL) crash safety.

Method	Path	Description
POST	/	Receive webhook event
GET	/health	Health check
GET	/replay	Replay WAL after crash

Auth: Authorization: Bearer {BRAINSAIT_API_KEY}

Event Types

Type	Source	Description
deployment	coolify, github-actions	App deployment events
alert	supervisor	Health alert notifications
recovery	supervisor	Auto-recovery events
workflow	supervisor	Workflow execution events
health	any	Periodic health pings
custom	any	User-defined events

---

Metrics Exporter (port 58083)

Prometheus-format metrics endpoint with server-side alert evaluation.

Method	Path	Description
GET	/metrics	Prometheus text format (192+ metric lines)
GET	/alerts	Currently firing alerts as JSON
GET	/health	Health check

Alert Rules

Alert	Threshold	Severity
DiskSpaceLow	> 85%	warning
MemoryHigh	> 85%	warning
CircuitBreakerOpen	> 0	critical
WorkersUnreachable	> 0	critical
PostgresDown	false	critical
RedisDown	false	critical
ContainersDown	> 0	critical

---

Grafana (port 3000)

Visual monitoring dashboard with pre-built ecosystem overview.

• URL: http://localhost:3000/
• Login: admin / brainsait2026
• Datasource: Prometheus (http://172.17.0.1:58083)
• Dashboard: BRAINSAIT Ecosystem (24 panels, 7 rows, 30s refresh)

Dashboard Rows

Row	Panels	Description
System Resources	6 gauges	Disk, Memory, Containers Running, Workers Reachable, CB Open, DB Status
Container Health	1 table + 1 timeseries	Color-coded container status + running/healthy/down over time
Worker API Status	1 table + 1 timeseries	Worker latency + reachability + latency distribution
Circuit Breakers	1 table + 1 timeseries	Failures by service + open/closed states
Alerts	1 table	Currently firing alerts with severity coloring
Container Resources	2 timeseries	Per-container CPU% and memory%
System Timeline	2 timeseries	Disk+Memory trend + supervisor uptime

---

Aggressive Test Results (67 tests, 100% pass)

Full-ecosystem test run on 2026-06-09:

Category	Tests	Passed	Failed
Port Availability	7	7	0
REST Gateway Core	5	5	0
FHIR Proxy	2	2	0
Security Module	3	3	0
All 19 Pulse Agents	19	19	0
Predictive Models	5	5	0
HF Models + Chat	2	2	0
External Proxy	6	6	0
Supervisor	2	2	0
IRIS Direct	2	2	0
IRIS Class Dispatch	2	2	0
Process Health	5	5	0
Total	67	67	0