Service Reference

Service Reference

API Gateway (port 58080)

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

Endpoints

Method	Path	Backend	Description
GET	/health	—	Gateway health + available services
GET	/routes	—	API discovery with examples
*	/fhir/{path}	localhost:52773	FHIR R4 proxy
*	/linc/{agent}	Local Python	Pulse AI agent (14 agents)
*	/hf/{action}	Local Python	HF models + chat
*	/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

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 .

---

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

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