User Requirements Document
Purpose: This document summarizes all system requirements in plain language, organized by platform and feature area. Status: Ready for Implementation
Platform Structure
The system consists of four separate applications:
- Portal - Used by hospital staff (doctors, nurses, receptionists, cashiers) to manage daily operations
- Console - Used by iHospita administrators to manage all hospitals on the platform
- Queue Display - Shown on TV monitors in waiting areas to display queue status
- Landing - Public marketing website for potential customers
Portal Platform (Hospital Staff)
The Portal is the main application used by hospital employees to manage patients, appointments, billing, and clinical operations.
Authentication & Security (Keycloak)
Identity Provider:
- The system uses Keycloak as the enterprise identity provider
- Keycloak provides OAuth2/OpenID Connect authentication
- Each hospital has its own isolated "realm" in Keycloak for complete user separation
Login Requirements:
- All staff members must log in with email and password
- Two-factor authentication (2FA) is required using email OTP codes
- After 8 hours of inactivity, users are automatically logged out
- Staff accounts are created by hospital administrators; no self-registration
Role-Based Access:
- Predefined roles: Owner, Admin, Doctor, Nurse, Receptionist, Cashier
- Hospitals cannot create custom roles; role templates are managed by Console
- Permissions are embedded in the JWT token issued by Keycloak
Patient Management
Patient Registration:
- Only staff members can register new patients
- System automatically creates a family membership account
- Each patient receives a unique Patient ID and digital Saving Card
- Required information: name, phone number, date of birth, emergency contact
- System tracks allergies, chronic conditions, and medical history
Patient Profile:
- Complete patient information including personal details and medical history
- VIP tier status and available discounts displayed prominently
- Allergies shown as warnings throughout the system
- View all past visits, lab results, prescriptions, and invoices
VIP & Loyalty System
Points-Based VIP Tiers:
- Patients earn 1 loyalty point for every $1 spent (configurable)
- Points accumulate at the family level, not individual patient level
VIP Tier Thresholds (Default, Configurable):
| Tier | Points Required | Discount |
|---|---|---|
| Silver | > 1,000 points | 5% |
| Gold | > 5,000 points | 10% |
| Platinum | > 10,000 points | 15% |
VIP Benefits:
- Automatic discounts on all services based on tier
- VIP status does NOT provide queue priority
- VIP discounts cannot be combined with promotional discounts
Queue Management
Queue Structure:
- Each doctor has their own separate queue
- No separate queues by department
- All patients served in first-come-first-served order
Queue Display:
- Current queue status displayed on TV monitors
- Patients see queue position and estimated wait time
- Audio announcement when patient's number is called
Appointment System
Booking Rules:
- Staff can book appointments for patients in advance
- Advance booking limit is configurable by each hospital
- System shows available time slots based on doctor schedules
Cancellation Policy:
- Patients can cancel appointments at any time without fee
- No penalties for cancellation or no-shows
- Cancelled appointments free up the time slot
Clinical Operations
Doctor Consultation:
- Access patient records from the queue
- Allergies displayed prominently as warnings
- Record SOAP notes (Subjective, Objective, Assessment, Plan)
- Enter vital signs: blood pressure, temperature, pulse, weight, height
- ICD-10 diagnosis coding
Prescription Management:
- Drug allergy checking with warnings
- Drug interaction checking
- Includes: medication name, dosage, frequency, duration, instructions
- Prescriptions sent to pharmacy queue automatically
Laboratory Orders:
- Categorized by type (hematology, biochemistry, microbiology)
- Turnaround time and sample requirements specified
- Costs automatically added to patient's invoice
Payment & Billing
Payment Methods:
- Cash, Card (Stripe), and Bank Transfer
- Partial payments allowed with no limit
- Points awarded after payment completion
Invoice Generation:
- Automatic generation when services are added
- VIP discounts calculated automatically
- Breakdown of services, discounts, and totals
- PDF printing and email delivery
Console Platform (iHospita Admin)
The Console is used by iHospita platform administrators to manage all hospitals, subscriptions, and system-wide settings.
Console User Roles
| Role | Access Level |
|---|---|
| Super Admin | Complete access to all features |
| Admin | Manage hospitals and users |
| Support | View-only + impersonation |
| Billing | Subscription and payment management |
Hospital Management
- Create new hospital accounts (auto-approved)
- View all hospitals on the platform
- Suspend or reactivate hospitals
- View usage statistics (users, patients, transactions)
Role Template Management
- Define default role templates (Doctor, Nurse, Cashier, etc.)
- Templates specify permissions for each role
- Templates copied to new hospitals on creation
- Changes only affect newly created hospitals
Support Impersonation
- Support staff can "impersonate" hospital users
- Temporary session (1 hour maximum)
- All impersonation sessions logged with full details
Theme Configuration
- Configure custom branding and colors per hospital
- Settings applied to Portal and Queue Display
- Predefined theme templates available:
- iHospita Blue (Default)
- Medical Green
- Royal Purple
- Warm Orange
- Professional Gray
- Custom
Queue Display (TV Monitors)
Specialized application for TV monitors in hospital waiting areas.
Display Features
- Now Serving: Current queue numbers at each counter/room
- Waiting Queue: List of waiting numbers organized by type
- Audio Announcements: Multi-language support (English, Khmer)
Technical Features
- Real-time updates via WebSocket/SSE
- Auto-reconnect on network loss
- TV-optimized: large fonts, high contrast, auto-fullscreen
- Multi-clinic support with unique URLs
Landing Website (Marketing)
Public-facing marketing site for the iHospita platform.
Website Sections
- Homepage: Hero section, feature highlights, testimonials, CTAs
- Features Page: Detailed explanations, screenshots, comparisons
- Pricing Page: Subscription tiers, feature comparison, FAQ
- Contact Page: Sales inquiry form, company information
Cross-Platform Requirements
Security Requirements
- All platforms require authentication (except public Landing and Queue Display)
- Two-factor authentication required for all staff
- Sessions expire after 8 hours of inactivity
- Complete data isolation between hospitals
- HTTPS (TLS) for all data transmission
- HIPAA compliance not required
Data Requirements
- Multi-Currency: USD (primary) and KHR (Cambodian Riel)
- Multi-Language: English and Khmer interface support
Performance Requirements
- 24/7 availability with minimal downtime
- Pages load within reasonable time
- Real-time features update within seconds
- System scales with growth in hospitals and users
Feature Summary by User Role
Hospital Owner
- Hospital Setup, User Management, Service Pricing, View Reports, All Staff Features
Doctor
- View Queue, Patient Consultation, Prescriptions, Lab Orders, View Results, Medical Certificates
Nurse
- Patient Check-In, Record Vitals, Assist Doctor, Vaccination Records
Receptionist
- Patient Registration, Check-In, Appointment Booking, Queue Management, Visitor Management
Cashier
- Process Payments, Generate Invoices, Issue Receipts, Daily Reconciliation, Payment History
Lab Technician
- View Lab Orders, Sample Collection, Enter Results, Flag Abnormals, Generate Reports
Pharmacist
- View Prescriptions, Check Stock, Dispense Medications, Patient Counseling, Inventory Updates
Console Admin
- Hospital Management, User Creation, Role Templates, Subscriptions, Theme Configuration, Analytics, Audit Logs