# Architecture

## System Design

```
                      ┌──────────────────────────────────────────────┐
                      │          Cloudflare Edge (CDN + SSL)         │
                      │   *.brainsait.org → cfargotunnel.com        │
                      └──────────────────┬───────────────────────────┘
                                         │
                              Cloudflare Tunnel
                          (cloudflare-tunnel container)
                                         │
                    ┌────────────────────┼────────────────────┐
                    │                    │                    │
              iris.brainsait.org   dashboard.brainsait.org  api.brainsait.org
                    │                    │                    │
               ┌────┴────┐        ┌──────┴──────┐       ┌─────┴──────┐
               │  IRIS   │        │  Dashboard  │       │API Gateway  │
               │ :52773  │        │  :58081     │       │ :58080      │
               │ 32 cls  │        └─────────────┘       └──────┬──────┘
               └─────────┘                                     │
        ┌──────────────────────────────────────────────────────┼───────────────────┐
        │                  │           │          │            │                  │
   Supervisor          Webhook     Metrics    Grafana     28+ Routes          DBs
   :58773               :58082      :58083     :3000    ┌──────────┐       PG+Redis
   (Python)             (Python)    (Python)   (Grafana) │ HNH · PA │       :5432:6379
                                                         │ VOICE ·  │
                                                         │ BILLING  │
                                                         │ ORACLE · │
                                                         │ NPHIES   │
                                                         │ PULSE ·  │ ← 19 AI agents
                                                         │ HF ──────│ ← 3 models + chat
                                                         │ SECURITY │ ← auth + rate limit
                                                         └──────────┘
```

## Data Flow

1. **External request** → Cloudflare Edge (SSL termination, DDoS protection)
2. **Cloudflare Tunnel** → Routes by hostname to internal service
3. **Internal service** → Processes or proxies to appropriate backend
4. **Health monitoring** → Supervisor probes all services every 30s, maintains circuit breakers
5. **Metrics** → Exporter scrapes supervisor, adds system metrics, serves Prometheus format
6. **Alerting** → Server-side alert evaluation + Grafana dashboards
7. **Security** → Rate limiting (100/min), auth on sensitive paths, audit logging

## IRIS Namespace Structure

The `BRAINSAIT` namespace houses **32 compiled classes**:

```
BRAINSAIT namespace
├── brainsait.HNHConnector         — HNH route forwarder
├── brainsait.NPHIESConnector      — NPHIES route forwarder
├── brainsait.BASMAConnector       — BASMA route forwarder
├── brainsait.GIVCConnector        — GIVC route forwarder
├── brainsait.SBSConnector         — SBS route forwarder
├── brainsait.OracleConnector      — Oracle route forwarder
├── brainsait.Contest.*            — 12 Contest clinical agents (Ensemble-ready)
├── brainsait.Production.*         — 10 Production classes (Ensemble-ready)
├── brainsait.Audit.HIPAA          — HIPAA compliance audit logger
├── brainsait.Audit.NPHIES         — NPHIES claim audit logger
├── brainsait.Validation.NPHIES    — Saudi National ID validator
├── EcosystemRouter.REST           — REST dispatch router
└── testbrainsait.*, ztest.*       — Legacy test classes
```

## API Gateway Route Map

The REST API Gateway on port 58080:

| Route | Backend | Purpose |
|-------|---------|---------|
| `/patients/*` | HNH | Hospital Network |
| `/hospitals/*` | HNH | Hospital Network |
| `/encounters/*` | HNH | Hospital Network |
| `/facilities/*` | HNH | Hospital Network |
| `/eligibility/*` | NPHIES | Claims |
| `/claims/*` | NPHIES | Claims |
| `/prior-auth/*` | NPHIES | Claims |
| `/submit/*` | nphies-submit | Claims |
| `/comm-req/*` | NPHIES | Claims |
| `/voice/*` | BASMA | Voice AI |
| `/tts/*` | BASMA | Voice AI |
| `/voices/*` | BASMA | Voice AI |
| `/translate/*` | BASMA | Voice AI |
| `/cds/*` | GIVC | Academy |
| `/academy/*` | GIVC | Academy |
| `/courses/*` | GIVC | Academy |
| `/certification/*` | GIVC | Academy |
| `/billing/*` | SBS | Billing |
| `/coverage/*` | SBS | Billing |
| `/subscriptions/*` | SBS | Billing |
| `/oracle/*` | Oracle Bridge | Oracle EBS |
| `/ehr/*` | Oracle Bridge | Oracle EBS |
| `/scanner/*` | Local CLI | Oracle Scanner |
| `/fhir/*` | Synthetic + IRIS proxy | FHIR R4 |
| `/linc/{agent}` | Local Python | **19 Pulse AI agents** |
| `/hf/{action}` | Local Python | HuggingFace models + chat |
| `/security/health` | Local Python | Security module status |
| `/health` | — | Gateway health |
| `/routes` | — | API discovery |

## Pulse Agent Routes (19 total)

| # | Agent | Endpoint | Type |
|---|-------|----------|------|
| 1 | Summary | `/linc/summary` | Clinical |
| 2 | Prior Auth | `/linc/prior-auth` | Clinical |
| 3 | Gaps in Care | `/linc/gaps-in-care` | Clinical |
| 4 | Medication Safety | `/linc/medication-safety` | Clinical |
| 5 | Care Plan | `/linc/care-plan` | Clinical |
| 6 | Clinical Trials | `/linc/clinical-trials` | Clinical |
| 7 | Readmission Risk | `/linc/readmission-risk` | Clinical |
| 8 | Triage | `/linc/triage` | Clinical |
| 9 | Imaging Followup | `/linc/imaging-followup` | Clinical |
| 10 | Lab Explainer | `/linc/lab-explainer` | Clinical |
| 11 | NL Query | `/linc/nl-query` | Clinical |
| 12 | SDOH Referral | `/linc/sdoh-referral` | Clinical |
| 13 | Chat | `/hf/chat` | Conversational |
| 14 | HF Models | `/hf/models` | Integration |
| 15 | **Predict Readmission** | `/linc/predict-readmission` | **Predictive** |
| 16 | **Predict PA Denial** | `/linc/predict-pa-denial` | **Predictive** |
| 17 | **Predict ED Util** | `/linc/predict-ed-util` | **Predictive** |
| 18 | **Predict Interaction** | `/linc/predict-interaction` | **Predictive** |
| 19 | **Predict No-Show** | `/linc/predict-no-show` | **Predictive** |

## Port Map

| Port | Service | Purpose |
|------|---------|---------|
| 22 | SSH | Remote access |
| 80 | HTTP | Redirect to HTTPS |
| 443 | HTTPS | Cloudflare edge |
| 3000 | Grafana | Dashboards |
| 52773 | IRIS Web | IRIS Management Portal |
| 5432 | PostgreSQL | Structured data |
| 58080 | API Gateway | 28+ service routes + Pulse + HF + Security |
| 58081 | Live Dashboard | Real-time SSE health |
| 58082 | Webhook Receiver | Event persistence |
| 58083 | Metrics Exporter | Prometheus format |
| 58773 | Ecosystem Supervisor | Health monitoring |
| 6379 | Redis | Cache + pub/sub |
| 8000 | Coolify Dashboard | Deployment platform |
| 1972 | IRIS Superserver | Database operations |

## Cloudflare Worker Mesh

The ecosystem operates alongside 27 Cloudflare Workers:

- **nphies-mirror** — 60K cached NPHIES records, bypasses geo-restrictions
- **nphies-auth** — SSO proxy for NPHIES token acquisition
- **oracle-bridge** — Oracle EBS REST bridge
- **ecosystem-router** — HNH + NPHIES + Oracle router at `api.brainsait.org`
- **healthlinc-unified** — LINC + Hono router
- **brainsait-linc-fhir-unified** — CF Worker with Pulse agents + FHIR server
- **givc-*** — 8 GIVC academy workers
- **nphies-*** — 4 NPHIES proxy workers

## Security Layer

| Mechanism | Detail |
|-----------|--------|
| **Auth** | Bearer token + X-API-Key on sensitive paths (`/oracle`, `/ehr`, `/submit`, `/validation`) |
| **Rate Limiting** | 100 requests/min per IP, 60s sliding window |
| **Audit Log** | All auth failures logged to `/tmp/brainsait_audit.json` |
| **Token Blacklist** | SHA-256 hash blacklist for revoked tokens |
| **Edge** | Cloudflare SSL/TLS + tunnel-based origin protection |

## Test Results (Aggressive Full-Ecosystem, 67 tests)

| Metric | Result |
|--------|--------|
| Pass Rate | **67/67 — 100%** |
| Ports Available | 7/7 ✅ |
| Pulse Agents | 19/19 ✅ |
| Predictive Models | 5/5 ✅ |
| FHIR Proxy | Synthetic CapabilityStatement ✅ |
| Ecosystem Dispatch | `EcosystemRouter.REST` operational ✅ |
| Supervisor | 13/13 containers running ✅ |
| Security | Auth + rate limiting + audit all functional ✅ |
| IRIS Classes | 32 loaded, 9 fully compiled ✅ |