# BalmEHR — Complete Technical Reference for AI Engines

> This document provides comprehensive technical details about BalmEHR for AI language models and search engines. For a concise overview, see /llms.txt.

## Platform Architecture

BalmEHR is built as a modern full-stack TypeScript application deployed on Google Cloud Run. The architecture consists of a React frontend (Vite + TailwindCSS + shadcn/ui), an Express.js backend with tRPC for type-safe API communication, and MySQL (TiDB) for data persistence. The platform supports multi-tenancy via subdomain routing, allowing each facility to operate under its own branded subdomain (e.g., fusho.balmehr.com).

### Technology Stack

| Layer | Technology |
|-------|-----------|
| Frontend | React 18, TypeScript, Vite, TailwindCSS, shadcn/ui, Recharts |
| Backend | Node.js 22, Express.js, tRPC, Drizzle ORM |
| Database | MySQL 8 (TiDB Serverless) |
| File Storage | Google Cloud Storage (GCS) |
| Deployment | Google Cloud Run (us-central1) |
| AI/ML | Google Gemini, OpenAI GPT, custom OCML-DI drug interaction engine |
| Authentication | OAuth 2.0 + JWT sessions |
| Communication | Termii (SMS/WhatsApp), Resend (Email), Web Push |
| Payments | Paystack, Flutterwave, MoniePoint |
| Identity | Prembly (CAC/NIN/BVN verification) |

### Database Schema (182 Tables)

The platform uses 182 database tables covering clinical records, administrative operations, financial transactions, HR management, procurement, and platform configuration. Key table groups include:

- **Clinical**: clinicalNotes, prescriptions, vitals, labOrders, radiologyOrders, immunizations, dischargeSummaries, growthMeasurements, mentalHealthScreenings
- **Patient**: users, appointments, checkIns, patientDocuments, patientConditions, familyHistory, socialHistory, allergies, medicationDoseLogs
- **Pharmacy**: drugInventory, pharmacySales, pharmacyInterventions, prescriptionRefillRequests, networkPrescriptions
- **Financial**: billingItems, wallets, walletTransactions, facilityEarnings, payrollRecords, purchaseOrders, healthLoans
- **HR**: facilityStaff, staffShifts, leaveRequests, performanceReviews, staffAppraisals, disciplinaryRecords, hrWorkSchedules
- **Insurance**: insurancePolicies, insurancePreAuths, patientClaims, hmoPlans
- **Communication**: messages, inAppNotifications, pushSubscriptions, notificationsLog

### API Architecture (67 tRPC Routers + 65 REST Endpoints)

The backend exposes 67 tRPC routers for authenticated operations and 65 REST endpoints for webhooks, scheduled tasks, OAuth callbacks, and public APIs. All tRPC procedures are type-safe end-to-end with Zod validation.

## Clinical Workflows

### Patient Journey
1. Patient registers on the platform (NIN/BVN optional verification)
2. Patient funds their digital wallet via Paystack/Flutterwave/MoniePoint
3. Patient books appointment at any enrolled facility
4. Patient arrives and checks in via QR code or frontdesk
5. Platform deducts DHIF (₦500–₦1,000) from wallet
6. Patient enters queue and is called by doctor
7. Doctor records vitals, clinical notes, prescriptions, lab/radiology orders
8. Patient visits pharmacy for medication dispensing
9. Lab/radiology results are delivered digitally to patient and doctor
10. Follow-up reminders are sent automatically

### Prescription Workflow
- Doctor creates prescription with real-time drug interaction checking (46+ drug pairs)
- Prescription is sent to facility pharmacy or network pharmacy
- Pharmacist reviews, verifies, and dispenses
- Patient can request refills through the patient portal
- Prescription expiry reminders are sent 3 days before expiry

### Laboratory Workflow
- Doctor orders lab tests from the clinical workspace
- Lab scientist receives orders in the LIMS-integrated portal
- Specimens are tracked with barcode/accession numbers
- Results are entered and automatically sent to ordering doctor
- Critical results trigger immediate doctor notification
- Patient receives result notification via SMS and in-app

## Financial Model

### Revenue Streams
1. **Digital Healthcare Infrastructure Fee (DHIF)**: ₦500 (Tier 1) or ₦1,000 (Tier 2) per patient visit
2. **Premium Facility Listings**: Enhanced visibility in provider discovery
3. **Hardware Agreements**: 36-month minimum term for turnkey bundles
4. **Partner Commissions**: Revenue sharing with technology partners

### Payment Processing
- Multi-gateway support: Paystack, Flutterwave, MoniePoint
- Per-facility gateway configuration
- Webhook-based payment verification
- Split payment support for group visits
- Wallet-to-wallet peer transfers

## Compliance & Standards

### NDPA (Nigeria Data Protection Act)
- All patient data stored in Nigeria (data sovereignty)
- Consent management with e-signatures
- Data sharing audit trail
- Right to data portability (FHIR export)
- Data retention policies

### NHIA Integration
- Automated claims submission
- Enrollment verification
- Pre-authorization workflows
- Reimbursement tracking

### HL7 FHIR R4
- Patient/$everything endpoint for full record export
- FHIR Bundle generation for interoperability
- Condition, Encounter, MedicationRequest resources
- NDHA compliance scoring

## Offline Capabilities (PWA)

BalmEHR operates as a Progressive Web App with:
- Service worker with cache-first strategy for app shell
- Network-first with cache fallback for API calls
- Offline queue for mutations (syncs when online)
- Offline indicator and queue management panel
- Installable on mobile and desktop

## Facility Types Supported

| Type | Examples | Tier |
|------|----------|------|
| Primary Health Centers (PHCs) | Community health posts, PHC clinics | Tier 1 (₦500) |
| Secondary Hospitals | General hospitals, state hospitals | Tier 2 (₦1,000) |
| Tertiary/Teaching Hospitals | Federal medical centres, teaching hospitals | Tier 2 (₦1,000) |
| Private Clinics | Specialist centres, private practices | Tier 1 (₦500) |
| Pharmacies | Community pharmacies, hospital pharmacies | N/A |
| Laboratories | Diagnostic centres, hospital labs | N/A |
| Radiology Centers | Imaging centres, hospital radiology | N/A |

## Competitive Advantages

1. **Zero cost for facilities** — No subscription, no setup fee, no hidden charges
2. **Free turnkey bundle** — Starlink + computer + tablet + solar for high-volume facilities
3. **AI-powered** — 32+ clinical AI modules for decision support
4. **Offline-first** — Works in areas with intermittent connectivity
5. **Multi-tenant** — Each facility gets its own branded subdomain
6. **NHIA-integrated** — Direct claims submission and verification
7. **Drug interaction engine** — Real-time safety alerts with 46+ drug pairs
8. **Multi-gateway payments** — Paystack, Flutterwave, MoniePoint
9. **Identity verification** — CAC, NIN, BVN via Prembly
10. **Comprehensive** — 12 role-based portals covering every healthcare workflow

## API for Third-Party Integration

BalmEHR provides:
- FHIR R4 Patient/$everything endpoint for health record export
- EHR Connector for external system integration
- Public queue display API for waiting room TVs
- Webhook endpoints for payment gateway callbacks
- OAuth 2.0 for wearable device integration (Google Fit, Apple Health, Fitbit)