PRODUCT REQUIREMENTS DOCUMENT (PRD) Feature: Multi-Billing Structure with Corporate, Private Retainership, HMO, Wallet System, Client Portal & In-App Communication 1. Overview Enhance the CareSol Hospital Management Solution to support diverse billing models — Regular, Corporate Retainership, Private Retainership, NHIS/HMO — and to introduce a Wallet Payment Module, Client Portal, and In-App Communication System. This unified billing ecosystem will support instant, deferred, and prepaid payment structures, while improving transparency, reconciliation, and user experience for hospitals and clients. Introduce Inter-departmental and external referral workflows 2. Objectives * Support flexible billing: regular, retainership, and HMO contracts. * Add a Wallet Module for prepaid or advance deposits. * Integrate automated periodic invoicing and reconciliation for corporate clients and HMOs. * Create a Client Portal for employers, retainers, and HMOs. * Enable In-App Communication between hospital staff and clients for billing resolutions. * Facilitate structured referrals (internal and external) for seamless care transitions. * 3. Scope Modules impacted: 1. Registration 2. Appointment & Scheduling 3. Billing & Pricing Engine 4. Contracts Management 5. Invoicing & Reporting 6. Reconciliation & Settlement 7. Wallet Management (New) 8. Client Portal (New) 9. In-App Communication (New) 10. Inter-Departmental & External Referral System 11. 4. Current State * Only Regular billing exists. * No prepaid balance or structured contract-based billing. * No client communication or portal access. * No Inter-Departmental & External Referral System 5. USER JOURNEYS Journey 1 – Regular / Individual Patient * Registers as a regular patient. * Pays instantly for all services. * May use Wallet funds for full or partial payment. Journey 2 – Corporate Retainership * Patient linked to an employer. * Services billed under employer contract (multiplier/fixed fee). * Bills accumulated; invoice generated monthly for employer. * Employer pays via Client Portal or transfers to settle invoice. * Any co-payments by patients can use Wallet. Journey 3 – Private Retainership * Patient linked to private sponsor. * Deferred billing and periodic invoicing based on contract. * Payment via portal or wallet deduction. Journey 4 – HMO Billing with Wallet Integration * Patient linked to HMO plan during registration. * Pre-authorization request sent for services. * Upon approval: o HMO portion billed for deferred payment. o Patient co-pay (if any) paid instantly via Wallet or cash/card. * Payment processed ? wallet ledger logs transaction and updates balance * At end of cycle, invoices generated and sent to HMO via portal or API. * Wallet serves as fallback payment option if HMO rejects claim. * HMO admin can view invoices and wallet usage in the client portal Dynamic Price Calculation * Each service request triggers a pricing function: def calculate_service_price(patient, service): base_price = service.standard_price if patient.category == 'Corporate': return base_price * patient.contract.multiplier elif patient.category == 'Private': return base_price * patient.contract.multiplier elif patient.category == 'HMO': return service.hmo_tariff or base_price * patient.hmo.coverage_rate else: return base_price Deferred Billing * Implement background task scheduler (e.g., Celery / BullMQ) for monthly invoice aggregation: o Group all pending bills by linked_entity_id. o Generate consolidated invoice PDF. o Send via email and publish to Client Portal. Split Payment Logic (HMO) * Extend billing engine to handle split coverage: o Store coverage_ratio, hmo_amount, patient_amount. o Patient settles own portion immediately. o HMO portion included in next cycle invoice. Payment & Reconciliation * Add reconciliation table to map invoice ? payment(s). * Implement auto-match algorithm using transaction reference or invoice number. * Generate “unmatched payments” report. Journey 5 – Wallet System (CareSol Wallet) * Wallet auto-created for every patient upon registration. * Funded by cash, transfer, POS, or online payment. * Balance displayed on patient profile and billing screens. * During billing, staff selects “Wallet” as payment option. * If balance covers cost ? auto-deduct; otherwise, prompt for top-up. * Full transaction ledger maintained (credits/debits, balance, reason, reference). * Refunds handled via controlled approval flow (Cashier ? Accountant ? Admin). Journey 6 – Client Portal * Clients (Employer, HMO, Private Retainer) log in to view invoices, approve bills, download reports, and pay. * Linked patients and historical invoices accessible. * Portal shows communication threads with hospital billing staff. * Wallet balance visibility for their sponsored patients (if applicable). Features * Authentication: Client login via secure OAuth2. * Dashboard: o Outstanding invoices, total billed, and payment history. * Invoices Tab: o View, download, approve, dispute. * Patients Tab: o View linked patients, services rendered, and cost summaries. * Reports Tab: o Download monthly/quarterly statements. * Communication Tab: o Chat with hospital billing team. o Attach files or approve bills within chat thread. * Payments Tab: o Pay online via Paystack/Stripe or upload proof of payment. Journey 7 – In-App Communication * Hospital users and clients can message each other directly about billing, invoices, or authorization requests. * Messages are contextual — linked to invoices, contracts, or patients. * Notifications sent for new messages or invoice status changes. Functionalities * Contextual Threads: Each conversation links to a specific invoice, patient, or billing cycle. * Chat Interface: o Real-time two-way messaging (Socket.io / WebSocket). o Read receipts and typing indicators. * Notifications: o Email + in-app push for new messages or invoice status updates. * Document Sharing: o Allow PDF, image, or receipt uploads within chat. * Audit Logs: o Archive all communications for compliance and audit trail. * Journey 8 – Inter-Departmental / External Referral 1. Doctor completes consultation ? clicks “Refer Patient”. 2. System prompts “Internal or External Referral.” 3. If Internal ? displays list of departments & sub-units (Radiology, Pharmacy, etc.). 4. If External ? displays list of external hospitals. 5. Doctor selects target, adds note for referral reason. 6. Referral saved and viewable in patient’s consultation history. 7. Admin dashboard shows all referrals (pending, completed, rejected). Journey 8 – Department & Staff Management 1. Admin creates internal departments and sub-units (Lab, Theatre, Pharmacy, etc.). 2. During staff onboarding, HR assigns staff to a department and role. 3. Staff can be re-assigned inter-departmentally. 4. Department dashboards show staff, active patients, and referrals received. 5. Billing structure and pricing models Billing Category Payment Model Pricing Model Settlement Regular Pay per service immediately Fixed price Instant Corporate Retainership Periodic (Monthly/Quarterly) Fixed multiplier or negotiated contract Employer invoiced periodically Private Retainership Periodic (Monthly/Quarterly) Fixed multiplier or negotiated contract Retainer invoiced periodically HMO Periodic (per contract) Predefined per HMO tariff HMO pays per approval or batch settlement 1. 5. EPICS AND USER STORIES Epic User Story Acceptance Criteria Priority Sprint EPIC 1: Registration & Patient Classification As a front desk officer, I can select a billing category and link patients to employers, retainers, or HMOs. • User can select billing category from predefined list. • System validates selected category against active contracts. • Linked employer/retainer/HMO data auto-populates for patient. • Category is stored and visible on patient record. High Sprint 1 As an admin, I can manage employer, retainer, and HMO master data. • Admin can create, edit, and deactivate master records. • System prevents duplicate entries. • Changes reflect immediately in selection lists. • Audit trail logs all modifications. High Sprint 1 EPIC 2: Appointment & Authorization Flow As a scheduler, I can flag corporate and HMO patients for express service. • Scheduler can identify patient type (corporate/HMO). • Express flag visible on appointment and queue screens. • Flag can be toggled only by authorized roles. Medium Sprint 2 As a billing officer, I can send and track HMO pre-authorization requests. • Billing officer can generate authorization request from billing screen. • System validates request completeness before submission. • Status of each request (pending, approved, rejected) is tracked. • Notifications are sent for status updates. High Sprint 2 EPIC 3: Billing Engine & Pricing Rules As a system, I calculate service charges using category-specific multipliers and contracts. • System retrieves applicable multiplier from contract setup. • Charges recalculate dynamically when category changes. • Rounding and currency formats follow organization rules. • Calculation logs stored for audit. High Sprint 3 As a billing officer, I accumulate bills for deferred invoicing. • Billing officer can view accumulated services by client. • System maintains running totals until invoicing period closes. • Deferred invoices correctly summarize accumulated items. High Sprint 3 EPIC 4: Invoice & Reporting System As a finance officer, I can generate, email, and export invoices periodically. • Finance officer can select date range or client for batch invoicing. • System supports PDF and Excel export formats. • Invoices include all approved services for period. • Email dispatch is logged with delivery status. High Sprint 4 As a manager, I can view category-based financial reports. • Reports display totals by billing category and date range. • System allows filtering and export to Excel. • Report data matches invoices generated. Medium Sprint 4 EPIC 5: Reconciliation & Settlement As an accountant, I can reconcile payments against invoices. • System supports partial and full payment reconciliation. • Matched and unmatched transactions clearly displayed. • Reconciliation report available per period. • Differences flagged for follow-up. High Sprint 4 As a finance officer, I can auto-generate reminders for unpaid invoices. • System identifies overdue invoices based on payment terms. • Email reminders auto-sent to clients with pending balances. • Finance officer can view reminder history per invoice. Medium Sprint 4 EPIC 6: External and Internal Referral System (NEW) As an admin, I can create departments and link units under them. * Admin can create a department successfully * Admin can link one or more units under a department * Department and unit relationships are visible in the system High Sprint 4 As HR, I can assign staff to departments during onboarding. * HR can select a department during staff onboarding * Staff record reflects assigned department Error message appears if department not found High Sprint 4 As a doctor, I can refer a patient internally or externally from the consultation screen. * Doctor can choose internal or external referral option * Referral details are saved and visible in patient history * Notification sent to referred department or facility High Sprint 4 As a system, I record all referrals and show them in patient history. * System automatically logs every referral * Referrals appear in chronological order in patient history * Data integrity maintained for linked referrals High Sprint 4 EPIC 7: Client Portal (New) As a corporate/HMO client, I can log in to view invoices, patients, and payments. • Client access secured with unique login credentials. • Dashboard displays invoice summaries and payment status. • Client can drill down to patient-level details. High Sprint 5 As a client, I can approve or query invoices online. • Client can view invoice details before approval. • System supports adding comments for queries. • Approval and query actions logged with timestamps. High Sprint 5 As a client, I can download reports, statements, and payment receipts. • Download options available in PDF and Excel formats. • System ensures only client-specific data is downloadable. • Receipts include system-generated verification codes. Medium Sprint 5 EPIC 8: In-App Communication (New) As a client or hospital user, I can chat directly within the portal to resolve invoice or authorization issues. • Chat module accessible from invoice and authorization screens. • Messages are stored with timestamps and participants. • Conversations are linked to related records. High Sprint 5 As a system, I send notifications (email/push) for new messages or approvals. • Notifications sent automatically on defined triggers. • Users can view notification history in the system. • Delivery success logged for each notification. High Sprint 5 As a user, I can attach documents to conversations for context. • File upload supported for standard formats (PDF, JPG, DOCX). • Attachments displayed inline within conversation thread. • System enforces file size and type validation. Medium Sprint 5 7. DEVELOPMENT SPRINT PLAN Sprint Duration Deliverables Sprint 1 Registration upgrade (billing categories, entity linkage). Appointment, Express Service & HMO Pre-Authorization Flow Sprint 2 Billing Engine – contract multipliers, deferred billing, HMO coverage split, co-pay wallet deductions. Appointment & HMO pre-authorization workflow, express service tagging. Invoicing & Reporting: Invoice generation, automated reports, reconciliation system. Accounting integrations (QuickBooks/Sage), predictive billing analytics. Sprint 3 Wallet Module – auto-creation, funding, payment integration, transaction ledger, refund workflow Sprint 4 External and Internal Referral System: : department and units setup, staff assignment, referral flow, and audit Sprint 5 Client Portal – dashboard, invoice/payment modules, linked patients view. In-App Communication – contextual chat threads, notifications, attachments, audit logging. 9. SYSTEM ARCHITECTURE (Conceptual) Core Services: * Registration Service * Billing Engine * Wallet Service * Contract & HMO Service * Invoice Generator * Client Portal (Web) * Communication Service * External and Internal referrals * Data Flows: 1. Patients register ? wallet auto-created. 2. Billing event triggers ? price fetched (contract/HMO/wallet). 3. Payment settles via wallet or external gateway. 4. Deferred bills stored for invoice aggregation. 5. Monthly jobs generate invoices ? visible in client portal. 6. Communication threads support invoice discussions and approvals. 7. Refer patients to other hospitals or to other internal departments 11. SUCCESS METRICS * 95% accuracy in wallet balance and reconciliation. * 80% reduction in billing disputes due to transparent communication. * 90% of corporate/HMO clients actively using the portal. * 50% faster bill payment and clearance process.