# Dokitab EMR & Hospital Management System — Technical & Clinical Specification

> DokiTab is an offline-first Electronic Medical Records (EMR) and Hospital Management System built for private clinics and hospitals in West Africa who want uninterrupted clinical documentation and billing during power outages, zero per-seat licensing fees, and ₦0 hardware CapEx via staff smartphones.

---

## 1. System Architecture & Multi-Tenancy

### 1.1 Backend Infrastructure
- **Framework**: Go (Gin Web Framework) flat-package architecture (`main` package) migrating to modular packages (ADR 0078), engineered for sub-50ms latency under high concurrent load.
- **Database Engine**: PostgreSQL 15+ running on CloudNativePG with automated failover, point-in-time recovery (PITR), and read replicas.
- **Row-Level Security (RLS)**: True database-level multi-tenancy enforced through PostgreSQL Row-Level Security policies. Every database transaction is executed inside the `RunInRLSTransaction(ctx, db, hospitalID, fn)` wrapper, which executes `SET LOCAL app.current_hospital_id = '<uuid>'` before query evaluation. This prevents cross-tenant data leaks even in the event of application-layer programming errors.
- **Authentication & Claims Context**: Cryptographic JWT bearer tokens containing authenticated `user_id`, `role`, and `hospital_id`. Handlers enforce security through `RequireAuth()`, `RequireDB()`, and tenant verification middleware.
- **Clock Drift Safeguards**: `ValidateClockDrift` middleware inspects the `X-Device-Timestamp` header against server UTC time (clamped to a max drift of ±300 seconds), rejecting backdated or forward-dated clinical entries.
- **Patient Identity Resolution**: `ResolvePatientID` handles merged patient records transparently; requests querying an obsolete temporary emergency MRN are automatically resolved to the master patient record ID without client error.

### 1.2 Web Admin Architecture (`clinical-sanctuary`)
- **Stack**: React 18, TypeScript, Vite, TailwindCSS, Axios API client with CSRF token exchange (`X-XSRF-TOKEN`).
- **Role-Based Access Control (RBAC)**: Enforced via `roleAllowedPaths` map in `src/lib/sidebarHelpers.ts` as the single source of truth across all 68 modules.
- **Supported Clinical Roles**:
  - `admin`: Full facility administration, billing configuration, staff rosters, audit log inspection.
  - `doctor`: Consultations, SOAP clinical notes, prescription ordering, lab ordering, surgery scheduling.
  - `nurse`: Bedside vitals, Medication Administration Record (MAR), intake/output fluid tracking, wound dressing, shift handovers.
  - `receptionist`: Patient registration, appointment booking, front-desk cashier invoice generation and payment receipts.
  - `pharmacist`: Inventory cataloging, batch stock receipts, FEFO dispensing queue, POS cashier balance.
  - `lab_tech`: Specimen accessioning, diagnostic test execution, result documentation, panic critical value escalation.
- **No Silent Failures**: UI components never swallow fetch errors with `.catch(() => [])`; all network and database failures display visible error banners and toast notifications to prevent patient safety risks.

### 1.3 Mobile Application (`mobile`)
- **Stack**: React Native (Expo), TypeScript, Redux Toolkit, React Native Vision Camera.
- **Operating Model**: BYOD (Bring Your Own Device) for nurses and doctors on personal smartphones.
- **Security Guardrails**: Ephemeral memory caching (no unencrypted SQLite storage of PHI on personal devices), biometric app lock after 2 minutes of inactivity, screenshot blocking, and app switcher privacy blur.

---

## 2. Inpatient Care & Bedside Nursing Workflows

### 2.1 Fluid Balance Tracking (`/api/inpatient/io`)
- **Purpose**: Quantitative tracking of fluid intake and output for post-operative, critical care, and pediatric inpatients.
- **Endpoints**:
  - `POST /api/inpatient/io`: Record fluid intake or output entry.
  - `GET /api/inpatient/io?patientId=<uuid>`: Fetch chronological fluid balance logs ordered by `recordedAt DESC`.
- **Validation**:
  - Volume must be positive and non-zero (`volume > 0`).
  - Types: `intake` | `output`.
  - Intake Categories: `IV Fluids`, `Oral Fluids`, `Blood Transfusion`, `Enteral Feed`.
  - Output Categories: `Urine`, `Vomit`, `Drainage Tube`, `Stool / Diarrhea`, `Blood Loss`.
- **Shift Net Calculation**: Automatic cumulative net balance calculated over 8-hour and 24-hour nursing shifts (`Net = Cumulative Intake - Cumulative Output`).

### 2.2 Wound Care Documentation (`/api/inpatient/wound`)
- **Endpoints**:
  - `POST /api/inpatient/wound`: Record anatomical wound assessment and dressing changes.
  - `GET /api/inpatient/wound?patientId=<uuid>`: List assessment history.
- **Clinical Attributes**:
  - `woundLocation`: Anatomical site description.
  - `woundType`: `Surgical Incision`, `Pressure Ulcer (Stage I-IV)`, `Traumatic Laceration`, `Diabetic Foot Ulcer`, `Burn (1st-3rd Degree)`.
  - `sizeCm`: Length × width dimensions.
  - `depth`: Surface, partial thickness, full thickness, cavity.
  - `appearance`: Granulating, sloughy, necrotic, epithelializing, infected.
  - `drainage`: None, serous, serosanguinous, purulent, foul odor.
  - `dressingApplied`: Primary and secondary dressing materials.
  - `nextDressingDue`: Required timestamp for subsequent dressing change.

### 2.3 Medication Administration Record (MAR)
- Tracks planned vs. administered medication doses for admitted inpatients.
- **Dispense to Bedside Workflow**: Doctor prescribes -> Pharmacist verifies & dispenses -> Nurse scans/verifies and records bedside administration.
- **Correction Protocol**: Dose entries cannot be deleted; errors require a correction entry explicitly referencing the prior `doseId` with mandatory clinical explanation (`reason`).

### 2.4 Nursing Shift Handovers (ADR 0009)
- Structured transition between outgoing and incoming nursing staff.
- **Immutable Clinical Snapshots**: Upon handover creation, the backend deep-copies current patient vitals (BP, SpO2, pulse, temperature) and pending medication/lab orders into JSONB snapshot columns. Handover review displays historical state at transition time, immune to later data mutations.

---

## 3. Emergency Triage & Rapid Registration

- **4-Tier Color Coding**:
  - `RED`: Immediate / Life-threatening (Target response: 0 minutes) — cardiac arrest, severe trauma, respiratory failure.
  - `ORANGE`: Urgent (Target response: <15 minutes) — chest pain, altered consciousness, acute severe bleeding.
  - `YELLOW`: Delayed (Target response: <60 minutes) — moderate fractures, controlled bleeding, high fever.
  - `GREEN`: Minor (Target response: <120 minutes) — minor cuts, chronic mild symptoms.
- **30-Second Rapid Registration**: Minimum viable emergency admission for unconscious or unidentified trauma patients. Requires only `isUnknown: true`, estimated age, perceived gender, and `broughtBy` (Ambulance / Police / Good Samaritan / Family), generating a temporary MRN (`EMR-TEMP-XXXX`).
- **Master Record Merging**: `POST /api/patients/:id/merge` merges an emergency temporary record into a verified patient record. All past vitals, nursing notes, lab requests, and charges are re-associated with the target master record, recording an immutable audit trail.

---

## 4. Pharmacy Inventory & FEFO Depletion

- **Depletion Strategy**: First-Expiring, First-Out (FEFO) prioritizing inventory batches ordered by `expiry_date ASC, received_date ASC`. Nearest-expiry stock is always allocated first to prevent shelf expiration losses.
- **Reorder Threshold Alerts**: Real-time automated notifications when available batch stock falls below `reorder_level`.
- **Dispensing Lifecycle**: `PENDING` -> `VERIFIED` -> `DISPENSED` -> `ADMINISTERED`.
- **Cashier POS & Shift Settlement**: Front-desk and pharmacy cash drawers enforce opening shift balance declaration, cash collection tracking, POS terminal reconciliation, and closing drawer balance lock.

---

## 5. Nigerian HMO Claims & Billing Module

- **Currency**: Denominated in Nigerian Naira (₦).
- **Tariff & Coding Engine**:
  - Standardized ICD-10 diagnosis code catalog.
  - Statutory NHIA Act 2022 Section 13 tariff calculation with automated 10% drug co-payment split.
  - State Health Insurance Scheme (SHIS) fee schedules: LASHMA (Ilera Eko in Lagos), FHIS (Abuja FCT), RIVCHPP (Rivers State), and KSCHMA (Kano State).
  - Private HMO fee schedules and procedure tariffs matching primary Nigerian HMOs (Hygeia, Reliance, AXA Mansard, Leadway, Avon, Total Health Trust).
- **Claim Lifecycle**: `DRAFT` -> `SUBMITTED` -> `IN_REVIEW` -> `APPROVED` / `REJECTED` -> `PAID`.
- **Clean-Claim Pre-Submission Rules**:
  - Validation of HMO policy number and enrolee eligibility before service dispatch.
  - Pre-authorization code requirements enforced for surgical and high-cost diagnostic procedures.
  - Split billing: automatic calculation of HMO-covered tariff versus patient out-of-pocket copayment.

---

## 6. Specialized Practice Verticals

### 6.1 Pharmacy Management (`/for/pharmacy`)
- Standalone outpatient and retail pharmacy operations.
- Direct counter POS sales, doctor prescription electronic queue, barcode scanning, batch expiry tracking, and wholesale supplier PO management.

### 6.2 Diagnostic Laboratories & HL7 Analyzer Interfacing (`/for/lab`)
- Specimen accessioning with unique barcoded sample identifiers.
- Specimen chain-of-custody tracking: `COLLECTED` -> `ACCESSIONED` -> `TESTING` -> `RESULT_ENTERED` -> `VERIFIED` -> `RELEASED`.
- Automated critical panic value notifications: immediate alerts sent to ordering physicians when laboratory findings breach biological thresholds (e.g. potassium < 2.5 or > 6.5 mmol/L).
- Digital report distribution: automated PDF result generation with physician digital sign-off and secure patient portal delivery.

### 6.3 Dental Practices & Tooth Charting (`/for/dental`)
- FDI Two-Digit World Dental Federation notation system.
- Interactive adult (32 teeth) and pediatric (20 deciduous teeth) graphical odontograms.
- Chairside surface charting (mesial, occlusal, distal, buccal, lingual) for caries, restorations, crowns, extractions, endodontics, and periodontal pockets.
- Procedure estimate catalogs with automated dental billing generation.

### 6.4 Physiotherapy & Rehabilitation (`/for/physio`)
- Joint Range of Motion (ROM) goniometric angle tracking across rehabilitation appointments.
- Visual exercise regimen builder with sets, repetitions, frequency, and patient home instruction printouts.
- Rehabilitation session package countdown billing (e.g., 6-session, 10-session packages) with automated utilization logs.

---

## 7. Growth Hub & Peer Referral Architecture (ADR 0083)

- **Peer Hospital Viral Loop**: Enables partner clinics, diagnostic labs, and healthcare professionals to refer neighboring practices to Dokitab.
- **Cryptographic Referral Codes**: Deterministic referral code generation and verification via public endpoint `GET /api/growth/validate-code/:code`.
- **Attribution & Incentives**: Multi-touch referral attribution tracking with automated subscription credit discounts upon successful facility onboarding.

---

## 8. Clinical Operations Management & Reliability (ADR 0084)

- **Real-Time Operations Cockpit**: Live tracking of emergency department wait times, bed occupancy percentages across wards, average length of stay (ALOS), and nurse-to-patient staffing ratios.
- **Business Continuity & Power Grid Resilience**:
  - Client-side SQLite/IndexedDB caching tolerating frequent generator cutovers, broadband drops, and NEPA/grid power failures.
  - Background bidirectional synchronization with conflict-free optimistic updates upon network restoration.
- **Disaster Recovery**: Automated point-in-time PostgreSQL recovery with zero-data-loss failover on Kubernetes infrastructure.

---

## 9. Security, Compliance & Data Sovereignty

- **Regulatory Compliance**:
  - **Nigeria Data Protection Act (NDPA 2023)**: Full compliance with Nigerian data sovereignty requirements, audit logging, consent frameworks, and patient access rights.
  - **HIPAA (US)**: Satisfies HIPAA Technical Safeguards (access control, integrity controls, audit controls, transmission security).
  - **Pan-African Privacy Standards**: Aligned with South Africa POPIA, Kenya DPA 2019, and Ghana DPA 2012.
- **Immutable Audit Trail**: Every clinical file creation, view, update, and export writes an append-only row to `audit_logs` containing `actor_id`, `hospital_id`, `ip_address`, `user_agent`, `action`, `resource_type`, `resource_id`, and payload diff.
- **Zero Seat Penalties Policy**: Dokitab strictly prohibits charging per-clinician or per-user licensing fees. Per-user fees incentivize staff to share generic "nurse" or "doctor" accounts, destroying the cryptographic audit trail required by NDPA 2023. Unlimited clinician seats are included across all paid tiers.

---

## 10. Commercial Pricing Architecture (ADR 0082)

- **Standalone-Free + 30k Hospital AI/Telemedicine Model**: Transparent pricing where all standalone facilities are 100% Free and only full hospital management with AI & Telemedicine costs money:
  - **Free Edition (₦0/mo — All Standalone Facilities)**: 100% Free for all standalone facilities: Outpatient Clinics, Community & Retail Pharmacies (`/for/pharmacy`), Diagnostic Laboratories (`/for/lab`), Dental Clinics (`/for/dental`), and Physiotherapy & Rehab Centers (`/for/physio`). Includes unlimited staff seats and all standalone vertical capabilities (FEFO dispensing, multi-till POS, HL7 analyzer feeds, barcode tube labels, FDI 32/20 5-surface odontograms, ROM/MMT/VAS tracking, WhatsApp HEP, HMO pre-auth, split-tender billing, and offline SQLite sync).
  - **30k Plan - Advanced Hospital Management, AI & Telemedicine Solution (₦30,000/mo or ₦300,000/yr)**: The only paid subscription tier. Built for full multi-department hospital management and primarily unlocks **Gemma 4 Multimodal AI Assistant** (Voice-to-SOAP Medical Scribe, AI clinical decision support, OCR folder/lab digitization) and **Telemedicine Video Consultations**, plus Inpatient Wards, Bedside MAR, nursing shift handover snapshots (ADR 0009), Operating Theatre/Surgery Management, PACS/DICOM Radiology, Blood Bank Safety, and Double-Entry GL Accounting.
- **Expansion Revenue Levers**:
  - Patient SMS and WhatsApp notifications via Termii (₦5 per SMS, ₦12 per WhatsApp delivery).
  - White-glove retrospective paper folder digitization & on-site onboarding (₦150,000–₦350,000 one-time).
  - Integrated POS card processing and instant bank transfer settlement (0.5% convenience fee).
- **Machine-Readable Pricing Document**: Refer to `/pricing.md` for complete specifications.

---

## 11. Machine-Readable Agent Discovery & Capabilities

- **Discovery Files**:
  - `/llms.txt`: Machine-readable concise index cataloging all documentation, vertical portals, and clinical whitepapers with token estimates.
  - `/llms-full.txt`: This full architectural and clinical specification document.
  - `/pricing.md`: Machine-readable structured pricing breakdown for autonomous buying agents.
  - `/agent-permissions.json` & `/.well-known/agent-permissions.json`: Machine-readable agent capability and safety boundary policy.
  - `/mcp-actions.json`: WebMCP tool definitions for autonomous agents.
  - `https://api.dokitab.com/openapi.json`: OpenAPI 3.0 specification.
- **Agent Policy Summary**:
  - Public browsing agents are permitted to inspect landing pages, vertical guides, pricing, and system specifications.
  - Autonomous agents may execute public validation flows (`/api/growth/validate-code/:code`, `/api/public/hospital/:slug`).
  - Unauthenticated access to private patient data (`/api/*`, `/admin/*`, `/portal/*`) is strictly forbidden and protected by cryptographic JWT and RLS safeguards.

---

## 12. Exhaustive 68-Module Clinical & Administrative Capability Catalog

Governed by canonical contract `shared/contracts/modules.json`, Dokitab operates 68 distinct hospital modules across 6 functional domains:

### Clinical Operations (14 Modules)

| Module ID | Module Title | Route / Path | Roles | Tier | Core Capability |
|---|---|---|---|---|---|
| `dashboard` | **Dashboard** | `/` | admin, super-admin, doctor... | GA | Real-time hospital-wide clinical activity overview, department census, and shift metrics |
| `triage` | **Triage & ER** | `/triage` | admin, doctor, nurse... | GA | 4-tier emergency triage categorization with 30-second unconscious patient rapid registration |
| `encounters` | **Encounters** | `/encounters` | admin, doctor, nurse... | GA | Outpatient clinical encounters, SOAP charting, vital trending, and diagnosis assignment |
| `referrals` | **Referrals & Care Transfers** | `/referrals` | admin, doctor, nurse | GA | Structured inter-hospital patient transfers and specialist referral handoff tracking |
| `inpatient` | **Inpatient Ward** | `/inpatient` | admin, doctor, nurse... | GA | Ward bed allocation, admission tracking, nursing care plans, and daily doctor ward rounds |
| `surgery` | **Surgery** | `/surgery` | admin, doctor, dentist... | GA | Operating theatre scheduling, pre-op anesthesia clearance, and post-op recovery notes |
| `antenatal` | **Antenatal & Maternity** | `/antenatal` | admin, doctor, nurse | GA | Antenatal care bookings, gestational timeline tracking, and WHO clinical partograph |
| `blood_bank` | **Blood Bank** | `/blood-bank` | admin, lab tech, doctor... | GA | ABO/Rh blood typing, cross-matching, donor registry, and cold chain temperature logs |
| `telemedicine` | **Telemedicine** | `/telemedicine` | admin, doctor | ALPHA | End-to-end encrypted remote video consultations and virtual clinical follow-ups |
| `ai` | **AI Clinical Intelligence** | `/ai` | admin, doctor, nurse... | GA | Local Gemma 4 multimodal clinical notes, automated OCR document parsing, and drug alerts |
| `screening` | **Health Screening** | `/screening` | admin, doctor, nurse | GA | Preventive health screening packages, corporate wellness exams, and biometric profiling |
| `pathways` | **Clinical Pathways** | `/pathways` | admin, doctor, nurse | GA | Standardized clinical protocol pathways for malaria, hypertension, and obstetric care |
| `messages` | **Staff Messaging** | `/messages` | admin, super-admin, doctor... | GA | Secure HIPAA/NDPA-compliant internal clinical messaging between care teams |
| `crash_cart` | **Crash Cart & Resuscitation** | `/crash-cart` | admin, doctor, nurse... | GA | Resuscitation tray inventory verification, defibrillator checks, and tamper-seal tracking |

### Specialty Clinics (10 Modules)

| Module ID | Module Title | Route / Path | Roles | Tier | Core Capability |
|---|---|---|---|---|---|
| `eye` | **Eye Care Clinic** | `/eye` | admin, doctor, nurse... | GA | Visual acuity testing, autorefractor metrics, and spectacle prescription POS dispensing |
| `physio` | **Physiotherapy** | `/physio` | admin, doctor, nurse | GA | Joint Range of Motion (ROM) goniometric tracking and therapy session package countdowns |
| `dental` | **Dental Suite** | `/dental` | admin, doctor, nurse... | GA | FDI Two-Digit adult (32) and pediatric (20) interactive tooth odontograms and treatment plans |
| `homecare` | **Home Care Services** | `/homecare` | admin, doctor, nurse | GA | Domiciliary nurse visit dispatch, mobile bedside vitals, and homecare session billing |
| `vaccination` | **Vaccination Clinic** | `/vaccination` | admin, nurse, doctor | GA | NPI vaccination schedules, cold-chain batch lot tracking, and digital immunisation cards |
| `family_care` | **Family Care** | `/family-care` | admin, doctor, nurse... | GA | Household-linked family clinical files, pediatric growth curves, and consolidated billing |
| `oncology` | **Medical Oncology Suite** | `/oncology` | admin, doctor, nurse... | GA | Chemotherapy cycle protocols, BSA-based dosage calculation, and tumor staging tracking |
| `dialysis` | **Hemodialysis Unit** | `/dialysis` | admin, doctor, nurse | GA | Hemodialysis run sheets, pre/post weights, dialyzer reuse cycles, and fluid balance logs |
| `nuclear_medicine` | **Nuclear Medicine & Decay** | `/nuclear-medicine` | admin, doctor, radiologist... | GA | Radiopharmaceutical isotope decay calculation, hot-lab safety, and dose administration |
| `cryopreservation` | **Cryopreservation & LN2** | `/cryopreservation` | admin, doctor, lab tech | GA | Liquid nitrogen dewar tracking, semen/embryo straw locations, and LN2 level logs |

### Patient Diagnostics & Intake (10 Modules)

| Module ID | Module Title | Route / Path | Roles | Tier | Core Capability |
|---|---|---|---|---|---|
| `radiology` | **Radiology & Imaging** | `/radiology` | admin, doctor, radiologist... | GA | X-ray, Ultrasound, CT/MRI orders with integrated PACS/DICOM image viewer |
| `queue` | **Queue Management** | `/queue` | admin, doctor, nurse... | GA | Departmental ticket queueing, waiting room display boards, and patient audio paging |
| `patients` | **Patients** | `/patients` | admin, doctor, surgeon... | GA | Master Patient Index (MPI), demographic records, national ID mapping, and biometric lookup |
| `appointments` | **Appointments** | `/appointments` | admin, doctor, nurse... | GA | Specialist appointment scheduling, doctor calendar slotting, and automated SMS reminders |
| `lab` | **Lab & Diagnostics** | `/investigations` | admin, doctor, nurse... | GA | Integrated hospital workflow capability |
| `lab_workbench` | **Lab Workbench** | `/lab/workbench` | admin, lab tech, doctor... | GA | Diagnostic lab sample processing, result validation, and critical panic value escalations |
| `home_collections` | **Home Collections** | `/lab/home-collections` | admin, lab tech, nurse | GA | Phlebotomy specimen field collection dispatch, GPS route planning, and sample chain |
| `digitization` | **Paper Digitization** | `/digitization` | admin, doctor, nurse... | GA | High-speed legacy physical case folder scanning, automated OCR indexing, and cloud archive |
| `hl7` | **HL7 & Lab Analyzers** | `/admin/analyzers` | admin, lab tech | GA | Integrated hospital workflow capability |
| `feedback` | **Patient Feedback** | `/feedback` | admin, doctor, nurse... | GA | In-clinic patient satisfaction surveys, CSAT net promoter scoring, and complaint triage |

### Finance, Tariffs & Revenue (10 Modules)

| Module ID | Module Title | Route / Path | Roles | Tier | Core Capability |
|---|---|---|---|---|---|
| `billing` | **Billing & Invoices** | `/billing` | admin, receptionist, pharmacist... | GA | Outpatient and inpatient invoice generation, multi-payor split billing, and payment receipts |
| `cashier` | **Cashier Workspace** | `/billing/cashier` | admin, receptionist, pharmacist... | GA | Shift opening/closing cash drawer declaration, POS terminal settlement, and cash balancing |
| `accounting` | **Accounting & Ledger** | `/admin/accounting` | admin, super-admin, hospital_admin... | GA | Double-entry general ledger, chart of accounts, trial balance, and automated P&L reports |
| `hmo_claims` | **HMO Claims** | `/billing/claims` | admin, receptionist, pharmacist... | GA | Integrated hospital workflow capability |
| `debtors` | **Debtors & Recovery** | `/billing/debtors` | admin, receptionist, accountant | GA | Patient debt aging schedules, automated payment installment plans, and recovery tracking |
| `packages` | **Care Packages** | `/billing/packages` | admin, receptionist, pharmacist... | GA | Fixed-fee bundled clinical care packages for antenatal, surgical, and wellness treatments |
| `corporate_billing` | **Corporate Billing** | `/billing/corporate` | admin, receptionist, pharmacist... | GA | Integrated hospital workflow capability |
| `catalog` | **Service Price List** | `/admin/catalog` | admin | GA | Master facility service price catalog, cash price lists, and HMO tariff mappings |
| `loss_risk` | **Loss Risk Dashboard** | `/admin/loss-risk` | admin | GA | Unbilled service revenue leakage detection, bill waiver audits, and pharmacy margin tracking |
| `financial_dashboard` | **Executive Financial Dashboard** | `/admin/financial-dashboard` | admin, super-admin, hospital_admin... | GA | Executive financial cockpit: department revenue splits, cash collections, and EBITDA trends |

### Pharmacy & Supply Chain (9 Modules)

| Module ID | Module Title | Route / Path | Roles | Tier | Core Capability |
|---|---|---|---|---|---|
| `inventory` | **Pharmacy Inventory** | `/admin/inventory` | admin, pharmacist, optician... | GA | First-Expiring, First-Out (FEFO) batch depletion, minimum reorder alerts, and supplier tracking |
| `orders` | **Pharmacy Orders** | `/admin/orders` | admin, pharmacist, doctor... | GA | Electronic prescription dispensing queue with barcode scanning verification |
| `prescription_templates` | **Rx Templates** | `/prescription-templates` | admin, doctor, nurse... | GA | Disease-specific standard prescription order sets and pediatric dosage formulas |
| `suppliers` | **Suppliers & Vendors** | `/pharmacy/suppliers` | admin, pharmacist, optician... | GA | Pharmaceutical vendor catalog, regulatory license tracking, and supplier contact directory |
| `purchase_orders` | **Purchase Orders** | `/pharmacy/purchase-orders` | admin, pharmacist, optician... | GA | Hospital Local Purchase Orders (LPO), multi-tier approval workflows, and goods receipt |
| `procurement` | **Procurement Workspace** | `/procurement` | admin, pharmacist, doctor... | GA | Hospital departmental requisition lifecycle from purchase request to warehouse intake |
| `stock_counts` | **Stock Audits** | `/pharmacy/stock-counts` | admin, pharmacist, optician | GA | Periodic physical inventory cycle counts, perpetual stock audits, and variance logs |
| `transfers` | **Branch Transfers** | `/pharmacy/transfers` | admin, pharmacist, optician | GA | Inter-facility medication transfers with dispatch authorization and receiving sign-offs |
| `controlled_register` | **Controlled Register** | `/pharmacy/controlled-register` | admin, pharmacist, nurse... | GA | Statutory controlled dangerous substance register, double-witness disposal, and logs |

### Hospital Administration & Governance (15 Modules)

| Module ID | Module Title | Route / Path | Roles | Tier | Core Capability |
|---|---|---|---|---|---|
| `group_overview` | **Hospital Group Overview** | `/admin/group-overview` | admin, super-admin, hospital_admin... | GA | Multi-hospital consolidated clinical patient volume, revenue, and bed occupancy metrics |
| `staffing` | **Staff Roster** | `/staffing` | admin, doctor, nurse... | GA | Clinical shift scheduling, doctor and nurse on-call rotas, and ward staffing ratio tracking |
| `hr` | **HR & Payroll** | `/hr` | admin, doctor, nurse... | GA | Staff personnel records, leave management, statutory PAYE deductions, and payroll processing |
| `departments` | **Departments** | `/admin/departments` | admin | GA | Hospital organizational hierarchy, medical specialty divisions, and cost centers |
| `network` | **Multi-Branch Network** | `/admin/network` | admin, super-admin, hospital_admin... | GA | Multi-branch healthcare facility network management, location routing, and central governance |
| `rooms` | **Rooms & Beds** | `/admin/rooms` | admin | GA | Inpatient ward room and bed configuration, daily bed rates, and occupancy status tracking |
| `assets` | **Asset Management** | `/admin/assets` | admin, doctor, nurse | GA | Biomedical equipment maintenance schedules, downtime tracking, and asset depreciation |
| `reports` | **Reports & Analytics** | `/reports` | admin, doctor, pharmacist... | GA | Statutory Ministry of Health epidemiology reporting, clinical census, and disease registries |
| `compliance` | **Compliance & Audit** | `/compliance` | admin, doctor, nurse... | GA | NDPA 2023 cryptographic audit trail inspection, PHI access monitoring, and security logs |
| `cms` | **Landing Page CMS** | `/admin/cms/landing` | admin, super-admin | GA | Public hospital marketing website CMS, doctor profiles, and service catalog editor |
| `cssd` | **CSSD Sterile Processing** | `/cssd` | admin, nurse, doctor | GA | Central Sterile Services Department (CSSD) autoclave cycle logs, biological spore tests, and trays |
| `mortuary` | **Mortuary & Cold Room** | `/mortuary` | admin, doctor, nurse | GA | Deceased patient intake, cold room vault slot assignment, embalming logs, and release certificates |
| `clinical_trials` | **Clinical Trials & IRB** | `/clinical-trials` | admin, doctor, nurse... | GA | Clinical trial protocols, Institutional Review Board (IRB) filings, and adverse events |
| `growth_hub` | **Facility Referrals & Rewards** | `/admin/growth` | admin, super-admin, hospital_admin | GA | Hospital referral network codes, doctor affiliate tracking, and subscription reward credits |
| `operations_manager` | **Operations & Quality** | `/admin/operations` | admin, super-admin, hospital_admin... | GA | Clinical operations cockpit: ER wait times, bed turnover, and nurse-to-patient ratios |


---

## 13. Competitive Landscape & Comparison Synthesis

### 13.1 DokiTab vs. Helium Health
- **Target URL**: https://dokitab.com/compare/dokitab-vs-helium-health
- **Hardware Profile**: DokiTab runs on clinicians' existing Android/iOS smartphones (BYOD moat), eliminating ₦15M-₦25M in desktop hardware and cabling CapEx. Helium Health historically deploys dedicated tablets or PC workstations.
- **Offline Resilience**: DokiTab maintains an embedded SQLite database on each mobile device. Nurses and doctors document bedside vitals, medications, and consultations completely offline during electrical power grid cuts; local cryptographic operation queues sync deterministically to PostgreSQL when internet returns. Helium Health requires active internet or local server rooms.
- **Pricing & Licensing**: DokiTab uses predictable facility capacity pricing in Naira (₦0 Free or ₦30,000/month flat) with UNLIMITED staff accounts, avoiding password-sharing and preserving NDPA audit logs. Legacy platforms charge per-seat or per-user fees (₦150k–₦500k+/month).
- **Data Residency**: DokiTab is hosted on AWS Lagos Local Zone and Cloudflare, ensuring 100% of patient health identifiers (PHI) remain within Nigerian sovereign borders under the Nigeria Data Protection Act (NDPA 2023).

### 13.2 DokiTab vs. Physical Paper Files
- **Target URL**: https://dokitab.com/guide/switch-from-paper-to-emr
- **Chart Retrieval Velocity**: DokiTab delivers instant file lookup (<0.5 seconds by patient phone, name, or MRN) from any consulting room or nurse smartphone. Paper medical records require dedicated physical file clerks and 30–45 minutes of search time per patient, causing severe outpatient congestion.
- **Elimination of Lost Case Files**: Private hospitals using paper lose or misfile 8% to 15% of records annually, creating dangerous clinical blind spots (unknown drug allergies, missing surgical history) and redundant lab re-testing. DokiTab unifies all encounters under a permanent Master Patient Index (MPI).
- **Statutory Billing & Revenue Leakage**: Paper billing permits up to 25% revenue leakage through unbilled nursing procedures, lost lab chits, and delayed HMO authorization submissions. DokiTab locks billing to service delivery with integrated NHIA Act 2022 Section 13 tariffs, automatic 10% drug copays, and Cashier POS shift drawer reconciliation.
- **Disaster Recovery & Physical Preservation**: Paper files are completely destroyed by hospital fires, flooding, termites, and humidity deterioration. DokiTab backs up all records continuously to AWS Lagos Local Zone with automated multi-zone replication and encrypted point-in-time recovery.
- **NDPA 2023 Audit Mandate**: Paper records offer zero access tracking—anyone entering a records room can view sensitive patient files undetected. DokiTab writes an immutable cryptographic audit log for every view, edit, and export.

### 13.3 DokiTab vs. Open-Source (OpenEMR / Bahmni / OpenMRS)
- **Target URL**: https://dokitab.com/compare/dokitab-vs-openemr
- **TCO Advantage ("The ₦20M Inverter Trap")**: While open-source software is free to download, deploying OpenEMR locally in Nigeria requires ₦15M–₦25M in upfront server room hardware, continuous inverter battery banks, industrial air conditioning, and ~₦350,000/month in diesel generator fuel. DokiTab is 100% cloud-managed with zero local server infrastructure.
- **Linux Engineering Retainers**: OpenEMR demands full-time in-house Linux systems administrators for security patches, MySQL maintenance, and backup scripts. DokiTab provides automated cloud updates and zero-maintenance SaaS reliability.
- **African Clinical Workflows**: OpenEMR requires extensive third-party plugin development for Nigerian healthcare realities. DokiTab includes pre-seeded Nigerian Essential Medicines List (NEML), standard NHIA tariffs, state health insurance rules (LASHMA, FHIS, RIVCHPP, KSCHMA), pharmacy FEFO expiry management, and Cashier POS shift balancing out of the box.

### 13.4 Best Hospital Management Software in Nigeria (2026 Comparison)
- **Target URL**: https://dokitab.com/best-hospital-management-software-nigeria
- **Scope**: Comprehensive 5-way comparative evaluation of DokiTab, Helium Health, OpenEMR, Medpack, and Insta by Practo.
- **Evaluation Dimensions**: Deployment topology, offline SQLite edge resilience during power outages, dedicated hardware CapEx, clinician seat licensing models, inpatient ward MAR, pharmacy FEFO batch expiry logic, and NDPA 2023 compliance.
- **Key Verdict**: DokiTab is ranked #1 for 90% of private Nigerian clinics and mid-sized hospitals seeking to eliminate server room capital expenditures and per-seat licensing penalties.

### 13.5 Top Helium Health Alternatives in Nigeria (2026)
- **Target URL**: https://dokitab.com/compare/helium-health-alternatives
- **Scope**: Evaluates alternatives for healthcare providers seeking lower total cost of ownership, flat capacity pricing in Naira, and offline operational continuity.
- **Migration Architecture**: Outlines the 3-step migration blueprint for transitioning from Helium Health or legacy desktop software to DokiTab in under 24 hours with zero clinical downtime.

### 13.6 How to Switch from Paper Records to EMR in 7 Days
- **Target URL**: https://dokitab.com/guide/switch-from-paper-to-emr
- **Scope**: Clinical operational blueprint detailing the "Forward-Only Day-1 Entry" model for transitioning private clinics from physical case folders to digital EMR without operational downtime.
- **Phased Schedule**: Day 1: Facility departments & price catalog; Day 2: Staff BYOD smartphone app setup; Day 3: Reception & Cashier POS; Day 4: Outpatient consults & e-prescriptions; Day 5: Pharmacy FEFO inventory; Day 6: Inpatient ward MAR; Day 7: 100% digital case notes.

### 13.7 PCN Electronic Pharmacy Regulations 2026 Compliance Guide
- **Target URL**: https://dokitab.com/blog/pcn-electronic-pharmacy-regulations-2026-nigeria
- **Statutory Authority**: Federal Republic of Nigeria Official Gazette, Vol. 113, No. 33 (S.I. No. 8 of 2026), under the Pharmacy Council of Nigeria (Establishment) Act, 2022.
- **Scope**: Authoritative compliance breakdown for Nigerian hospital outpatient pharmacies, community pharmacies, and telehealth entities.
- **Mandated Invariants**: Complete statutory ban on online sale or delivery of Dangerous Drugs Act substances (Reg 24 & 47; ₦2.5M fine/2 years imprisonment), single-fill atomic database lock on e-prescriptions (Reg 18(7)), 180-day automated prescription expiration (Reg 20(7)), mandatory patient NIN authentication and adult-only gating (Reg 22 & 36), prescriber MDCN registration metadata stamping (Reg 20(4)), 5-year data retention under NDPA 2023 (Reg 30), and turnkey readiness for the National Electronic Pharmacy Platform (NEPP) central nodal gateway (Reg 36).

---

## 14. Canonical Links & Verification Endpoints

### 14.1 Canonical Documentation URLs
- **Homepage**: https://dokitab.com/
- **PCN 2026 Regulations Guide**: https://dokitab.com/blog/pcn-electronic-pharmacy-regulations-2026-nigeria
- **Best EMR in Nigeria Review**: https://dokitab.com/best-hospital-management-software-nigeria
- **Helium Health Comparison**: https://dokitab.com/compare/dokitab-vs-helium-health
- **OpenEMR Comparison**: https://dokitab.com/compare/dokitab-vs-openemr
- **Helium Health Alternatives**: https://dokitab.com/compare/helium-health-alternatives
- **Switch from Paper to EMR Guide**: https://dokitab.com/guide/switch-from-paper-to-emr
- **Interactive TCO & Inverter Calculator**: https://dokitab.com/calculator
- **Pharmacy Operations Hub**: https://dokitab.com/for/pharmacy
- **Diagnostic Lab Hub**: https://dokitab.com/for/lab
- **Dental Operations Hub**: https://dokitab.com/for/dental
- **Physiotherapy Operations Hub**: https://dokitab.com/for/physio
- **Clinical Knowledge Base**: https://dokitab.com/resources
- **Support & Onboarding**: https://dokitab.com/support
- **Privacy Policy & NDPA Compliance**: https://dokitab.com/privacy.html
- **Terms of Service**: https://dokitab.com/terms.html

### 14.2 Machine-Readable Agent Discovery & Tool Schemas
- **Machine-Readable Pricing**: https://dokitab.com/pricing.md
- **Concise LLM Directory**: https://dokitab.com/llms.txt
- **Full Architectural Specification**: https://dokitab.com/llms-full.txt
- **Agentic Resource Discovery (ARD) Manifest**: https://dokitab.com/.well-known/ard.json
- **AI Catalog Manifest**: https://dokitab.com/.well-known/ai-catalog.json
- **Agent Permission Policy**: https://dokitab.com/agent-permissions.json
- **WebMCP Action Declarations**: https://dokitab.com/mcp-actions.json
- **OpenAPI 3.0 Specification**: https://api.dokitab.com/openapi.json

### 14.3 Verification Endpoints & API Health Contracts
- **System Health Check**:
  - `GET https://api.dokitab.com/health`
  - Response: `{"status":"healthy","database":"connected","version":"2026.9"}`
- **Growth Code Verification**:
  - `GET https://api.dokitab.com/api/growth/validate-code/:code`
  - Response: `{"valid":true,"code":"DOKI-XXXX","discountPercent":10}`
- **Public Hospital Identity Verification**:
  - `GET https://api.dokitab.com/api/public/hospital/:slug`
  - Response: `{"name":"Facility Name","state":"Lagos","ndpaVerified":true}`
- **Verified Entity Knowledge Graph Profiles**:
  - Crunchbase: https://www.crunchbase.com/organization/dokitab
  - LinkedIn: https://www.linkedin.com/company/dokitab/
  - Google Maps Entity: https://maps.app.goo.gl/zNsrYF5ucdXwnXce6 (CID: 18265588325607316702)
  - GitHub Monorepo: https://github.com/dokitab/dokitab