# 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

```bash
# 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** |