Skip to content

ARCHITECTURE

Jump to bottom
Fadil369 edited this page Jun 9, 2026 · 1 revision

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 ✅

Clone this wiki locally