# FlowRise HMS - Project Roadmap A modular, extensible Hospital Management System built with Laravel and Filament. ## Technical Principles - All domain models must be FHIR-compatible for data exchange - All modules must be Composer-installable independently - Patient identifiers use UUID for cross-system stability - Sensitive data encrypted at rest - **ICD-11** as primary coding standard (ICD-10 fallback) --- ## Phase 1: Foundation (Complete) - [x] System Setup (org config, branding, timezone) - [x] Facility Configuration (departments, wards, beds, service units) - [x] Location Hierarchy (facility → building → floor → room → bed) - [x] Core Traits (HasAddress, HasContact) - [x] **FHIR**: Organization, Branch → Organization, Location → Location, Department → HealthcareService *(read/search via Phase 11 FHIR module)* --- ## Phase 2: Patient Module (Complete) - [x] Patient registration & demographics (UUID-based) - [x] Patient identifiers (MRN auto-generation) - [x] Emergency contacts & relationships - [x] Patient documents & photos - [x] Sensitive data encryption (PII fields) - [x] **FHIR**: Patient *(CRUD/search via Phase 11 FHIR module; transformer in Patient module)* --- ## Phase 3: Staff Module (Complete) - [x] Employee profiles & credentials - [x] Department/specialty assignment - [x] Role-based access (Provider, Nurse, Admin) - [x] **FHIR**: Practitioner, PractitionerRole *(CRUD/search via Phase 11 FHIR module; transformers in Staff module)* --- ## Phase 4: Clinical Module (Complete) - [x] Encounters (inpatient, outpatient, emergency, virtual) - [x] Allergies & adverse reactions - [x] Vital signs recording - [x] Clinical notes - [x] Service requests, request items, and task fulfillment - [x] Medication Administration (MAR) — model, service, board, dose reminders, pending-fulfillment widget, relation manager, factories, flow tests - [x] ADT encounter location events (admit/transfer/discharge bed tracking) - [x] **FHIR**: Encounter, Condition, AllergyIntolerance *(read/search via [Phase 11](#phase-11-interoperability-fhir-module--in-progress) FHIR module)* - [ ] **FHIR**: DocumentReference *(Deferred to Phase 11 interoperability work)* Note: the functional clinical workspace and MAR flows are built; dedicated module test coverage can still be expanded beyond the current 22 test files. --- ## Phase 5: Pharmacy Module (Lean, Complete) - [x] Medication catalog (lean) - [x] Role-agnostic medication ordering via existing ServiceRequest/RequestItem - [x] Dispensing workflow with stock decrement - [x] Pharmacy POS checkout and prescription fulfillment - [ ] **FHIR**: Medication, MedicationRequest, MedicationDispense *(Deferred to Phase 11 interoperability work)* --- ## Phase 6: Appointments Module (Complete) - [x] Scheduling system - [x] Calendar views - [x] Waitlist management - [x] **FHIR**: Appointment, AppointmentResponse *(API registration in Phase 11)* - [ ] **FHIR**: Schedule, Slot *(No Schedule/Slot models exist yet; Slot depends on Schedule which references HealthcareService. Implementation deferred until scheduling model design is complete.)* Note: appointment CRUD, waitlist, outbox, calendar UI, and model factories are built; recurrence rules remain metadata-only until an expansion engine is implemented. --- ## Phase 7: Diagnostics Module (Complete) - [x] Clinical request-item bridge into diagnostic fulfillments - [x] Starter diagnostic catalog, panels, and reference ranges - [x] Core fulfillment/report/file/specimen/study/media schema (19 tables; HL7 deferred) - [x] Structured observation persistence and report-version linking - [x] Filament resources, relation managers, and discipline-aware workflows - [x] Clinical workspace template-driven lab result entry - [x] Lab result printing for patients and walk-in guests - [x] **FHIR**: Observation *(read/search via [Phase 11](#phase-11-interoperability-fhir-module--in-progress) FHIR module)* - [ ] **FHIR**: DiagnosticReport, Specimen, ImagingStudy *(Deferred to Phase 11 interoperability work)* - [ ] **HL7**: LIS message log and MLLP *(Deferred — last across all modules)* --- ## Phase 8: Inventory Module (Complete) - [x] Module scaffold, providers, and Filament plugin - [x] v1 schema (14 migrations including lot tracking, 13 models including `DocumentSequence`, document numbering) - [x] Stock ledger with lot tracking and FEFO decrement, purchase orders, requisitions, inter-branch transfers, stock adjustments (16 services including 5 PDF generators) - [x] Issue-to-pharmacy bridge via Core `StockProviderContract` → Pharmacy `StockService` - [x] Filament resources (7), PDF documents (GRN, vouchers, transfer notes, adjustment vouchers, stock cards) - [x] Filament workflow actions: PO submit/receive/close, requisition approve/decline, transfer ship/receive - [x] Analytics report page (8 chart widgets, CSV export) and `MyWardRequestsWidget` - [x] Feature tests (21 files — ledger, PO, requisition, issue/close, transfers, adjustment, pharmacy bridge, toggles, lot/FEFO, PDFs, report, widget, stock alerts) - [x] Requisition issue/close Filament actions (issue on Items RM + Fulfill shortcut; close on table/view) - [x] Stock adjustment UI and partial-receive forms in Filament - [x] Feature toggle enforcement (`FeatureSettings` toggles gated in services/resources) - [x] P0 fixes: transfer ship `stockTransferId`, pharmacy unit conversion, requisition item refresh - [x] Pharmacy Stock Items → Request from central store - [x] Lot tracking migration and FEFO ledger decrement with feature tests - [x] Phase 2 hub-and-spoke integration (optional Core contracts, unified low stock, MAR ward consumption, requisition notifications) - [x] Auto-reorder draft PO generation from dispensary low stock - [x] Scheduled reorder alerts (`inventory:check-stock-alerts`, scheduler + `NotificationSettings` + email/database notification) - [x] **FHIR**: InventoryItem read/search *(Implemented in Phase 11 FHIR module)* - [ ] **FHIR**: SupplyDelivery *(Deferred to Phase 11 interoperability work)* --- ## Phase 9: Billing Module (Complete) - [x] Invoice generation - [x] Payment tracking - [x] Service catalog with pricing - [x] **Works WITHOUT insurance** - cash patients fully supported - [x] Payment gateways, receipts/PDFs, reports, and billing notifications - [x] Model factories (8) - [x] Encounter cancellation billing (voids draft invoices on cancel) - [x] Financial hold integration (blocks fulfillment for unpaid prepay-required services) - [x] Pay-now links in invoice notifications - [x] Void invoice Filament action - [x] PaymentIntent and BillingWebhookEvent Filament resources - [x] Payment View page with allocations relation manager - [x] Invoice line insurance columns in Filament - [x] Due date management in Filament - [x] Overdue reminders and scheduler (`invoices:check-overdue` + `InvoiceUnpaidMail`, reminder cooldown) - [x] Refunds, write-offs, deposits, payment plans - [x] **Patient deposits ledger** — record, apply to invoices, patient balance display - [x] Appointment check-in billing automation (`auto_invoice_on_checkin` setting) - [x] Per-line gateway checkout - [x] Paystack driver via musheabdulhakim/paystack SDK --- ## Phase 10: Insurance Module (Complete) - [x] Insurance provider core models and extensible multi-payer architecture - [x] Patient insurance policies - [x] Claim generation and submission workflows - [x] Claim response tracking and reconciliation - [x] NHIS XML connector and generic private-insurer connector foundation - [x] Payer admin, claim batch UI, generate-claims page, NHIS settings - [x] Model factories (9) - [ ] Phase 2 feedback XML import *(Deferred — webhook feedback path exists; batch XML import not built)* - [ ] NHIS catalog sync implementation *(placeholder returns `processed: 0`)* - [ ] Dedicated PatientPolicy/TariffItem Filament resources *(Deferred — models exist; admin resources not built)* - [ ] **FHIR**: Coverage, Claim *(Deferred to Phase 11 interoperability work)* --- ## Phase 11: Interoperability (FHIR Module — In Progress) - [x] FHIR module infrastructure (validator, search, pagination, metadata) - [x] Patient, Practitioner, PractitionerRole API endpoints — full CRUD (Sanctum auth; transformers in Patient/Staff modules) - [x] Organization, Location, HealthcareService API endpoints — read/search (conditional registration via class_exists) - [x] Encounter, Condition, AllergyIntolerance API endpoints — read/search (Clinical module transformers) - [x] Observation API endpoint — read/search (Diagnostics module transformer) - [x] Appointment, AppointmentResponse API endpoints — read/search (Appointment module transformers) - [x] InventoryItem API endpoint — read/search (Inventory module transformer) - [ ] Additional FHIR resource transformers and API registration (DiagnosticReport, Claim, Coverage, ServiceRequest, Medication*, etc.) - [ ] Slot, Schedule FHIR resources (needs model design — see Phase 6) - [ ] SMART on FHIR authentication - [ ] Bulk data export ($export) - [ ] CCD document generation --- ## Post-Phase Cleanup (Remaining) - [ ] **FHIR** — Register remaining resource transformers (DiagnosticReport, Claim, Coverage, ServiceRequest, etc.); full CRUD where needed; SMART on FHIR; bulk `$export` - [ ] **Api** — Domain REST resource endpoints beyond Sanctum auth login/logout; expand Scribe coverage - [ ] **Clinical** — Expand dedicated module test coverage beyond current 22 test files - [ ] **Appointment** — Recurrence rule expansion engine (metadata-only today) - [ ] **Insurance** — Phase 2 feedback XML import; NHIS catalog sync implementation; dedicated PatientPolicy/TariffItem Filament resources - [ ] **Global interoperability** — Remaining per-module FHIR resource endpoints and HL7/LIS integration (deferred from individual module phases) --- ## Future Phases (Not in Initial Scope) - Multitenancy Module - Telemedicine Integration --- # How to Contribute ## Getting Started 1. Fork the repository 2. Clone your fork locally 3. Install dependencies: `composer install` 4. Set up your development environment 5. Pick an uncompleted phase or item from the roadmap ## Extensibility Guidelines When building new modules: 1. **Modular First**: Create as a separate module in `Modules/` 2. **Composer-Installable**: Include `composer.json` in your module 3. **FHIR Compatible**: Implement FHIR resources for your domain 4. **Tenant-Aware**: Design with future multitenancy in mind 5. **Document**: Update roadmap.md with your module's phase ## FHIR Compliance Requirements All data models should: 1. Map to appropriate FHIR resources 2. Support standard FHIR search parameters 3. Implement FHIR validation rules 4. Handle FHIR error responses correctly ## Testing Requirements - Write unit tests for all new features - Include integration tests for module interactions - Ensure FHIR resource validation passes - Test with both empty and populated data scenarios ## Submitting PRs 1. Create a feature branch from `main` 2. Follow coding standards (use `composer lint:fix`) 3. Write tests for your changes 4. Update documentation and roadmap if applicable 5. Submit PR with clear description of changes --- ## License This project is open source and available under the MIT License.