Backend EMR System

Comprehensive Technical Documentation & Architecture Reference

1. System Overview

The Backend Electronic Medical Record (EMR) system is a robust, clinical application designed to support family-centered community healthcare. It serves as the primary system of record, hosting patient registration details, location hierarchies, doctor and provider scheduling, home visits, clinical consultations, billing, and system audit trails.

The backend is built as a web application that exposes administrative panels to clinic operators, care teams, and billing clerks, while also exposing standard REST APIs for bidirectional synchronization with offline-first Flutter mobile applications.

Core Technical Stack

Backend Framework: Laravel 13.0 (utilizing PHP 8.4)
Frontend Engine: Blade Template Engine, styled using Bootstrap 5 (integrated via the premium UBold theme layout) and bundled with Vite
API Security: Laravel Sanctum for token-based mobile app authentication
Database Layer: Relational Database (typically SQLite for local development, MySQL/PostgreSQL for production) with transactional safety guards

2. Architectural Patterns

The application strictly enforces separation of concerns through clean design patterns.

The Service-Layer Pattern

To avoid thick controllers, the system isolates business rules inside dedicated Service classes under the app/Services/ directory. Controllers are responsible only for request validation, authorization checks, routing response models, and flash messaging, while services contain Eloquent queries, transaction wrappers, and state mutations.

Reusable Trait Interfaces

Cross-cutting model functionalities are structured as Traits in the app/Traits/ directory:

HasUuid: Automatically registers boot listeners to assign a UUIDv4 string during model creation. This UUID is critical for offline-mobile synchronization as it acts as a immutable, globally unique lookup key, preventing primary key collisions when inserting records from mobile clients.
Auditable: Registers observers to automatically record database state changes. It logs the user who made the change, the event type (created, updated, deleted), the original values, the updated values, the active request URL, IP address, and client User-Agent. Sensitive columns (such as password and remember_token) are automatically filtered out.

// Example of Auditable usage in Models
class Patient extends Model
{
    use Auditable, HasFactory, HasUuid, SoftDeletes;
    
    // Model attributes automatically audited on changes...
}
            

3. Database Schema & Core Models

The schema maps out clinical structures, administrative bounds, and geographical groupings. The key database tables and models are defined as follows:

Model Name	Table Name	Core Responsibilities & Fields
User	`users`	Standard authentication model. Belongs to many roles. Can be associated directly with a `Family` (as a contact) or a `Doctor`.
Doctor	`doctors`	Represents medical practitioners. Contains `specialty`, active state, and links to assigned `families` and `home_visits`.
Family	`families`	Household group profile. Tracks active/inactive status, socioeconomic parameters, water supply details, and dynamic health risk scores.
Patient	`patients`	Detailed clinical file. Structured into 16 sections (details below). Belongs to a `family` household.
HomeVisit	`home_visits`	Scheduling engine records. Statuses include: `scheduled`, `completed`, and `missed`.
Consultation	`consultations`	Full clinical encounter log. Records vitals, pathological history, medications, vaccinations, and follow-up plans.
Payment	`payments`	Billing transactions. Tracks mobile money provider (MTN, Airtel, Zamtel) and transaction reference.
Subscription	`subscriptions`	Tracks subscription status and billing periods for families.
Attachment	`attachments`	Polymorphic uploads (images, PDFs) linked to payments (receipts) or consultations (clinical files).

Geographical Hierarchy

To coordinate field health initiatives, locations are stored in a rigid parent-child hierarchy:

Country → Province → District → Constituency → Ward → Village

Families and Patients are assigned a village_id, placing them precisely within the administrative jurisdiction of specific clinics and health workers.

Patient Clinical File Structure (16 Sections)

The Patient model features a massive schema designed to hold a complete, holistic health record:

Patient Identification: Base details (name, national ID, gender, birth date, phone).
Family & Social Context: Relationship to household head, living arrangements, support systems.
Personal Medical History: Coded list of chronic conditions, diagnosis dates, and active treatments.
Surgical History: List of historical surgical interventions.
Allergies: Drug, food, and environmental allergies, including reaction severities.
Medication History: Current medication lists, adherence tracking, and reasons for non-adherence.
Immunization History: Complete childhood and adult vaccine log.
Reproductive Health: Menarche age, LMP, gravida, para, abortions, contraceptive methods, ANC details.
Lifestyle & Health Behavior: Tobacco use, alcohol intake frequency, diet patterns, and physical activity level.
Occupational & Environmental Risks: Workplace hazards, home environmental exposures.
Family History: Genetic conditions and diseases present in maternal/paternal lineage.
Physical Examination: Structured notes on system-by-system examinations.
Screening Record: Audits for cancer, diabetes, hypertension, and other surveillance screenings.
Dispensary Classification: Core risk group classifications (Groups I through IV).
Health Problem List: Active diagnosis registries.
Individual Care Plan: Custom health objectives and clinical directives.

4. Dynamic Family Health Scoring

A core feature of the EMR is the dynamic health score evaluation running inside the Family model's saving hook. Every time a family profile or a related patient file is updated, the system recalculates the family_health_score (a weighted cap value from 0 to 100) and updates the family_health_risk_level.

Scoring Breakdown

Disease Burden (Max 30 points): Evaluates the clinical severity of household members. Adds 10 points for each member in Dispensary Group III (Chronic Condition) and 20 points for each member in Dispensary Group IV (Disability).
Vulnerable Ages (Max 20 points): Adds 10 points if the family has children under 5 years old. Adds 10 points if the family includes elderly members (aged 60 or above).
Social Determinants (Max 20 points): Adds 5 points for each adverse indicator:
- Mud-walled housing structure
- Informal settlement land tenure
- Unprotected well or river as the primary water source
- Pit latrine or absent toilet facilities
- Lack of electricity access
Lifestyle Risks (Max 15 points): Adds 5 points if any household member is a current smoker. Adds 10 points for harmful alcohol use (5 points for regular/occasional use). Adds 5 points if the household is flagged as sedentary.
Mental & Social Risks (Max 15 points): Adds 5 points for each logged social risk factor (e.g. domestic violence risk, social isolation).

Risk Level Classifications

Health Score Range	Risk Level Classification	Clinical Action Priority
0 – 25	Low Risk	Routine annual wellness check-up.
26 – 50	Moderate Risk	Bi-annual checkups, targeted health education.
51 – 75	High Risk	Quarterly visits, medical provider care coordination.
76 – 100	Very High Risk	Priority monthly clinical intervention and active follow-up.

5. Access Control & RBAC

The backend secures routes and resources using role-based gates defined in AppServiceProvider and checked via Laravel's can: middleware or policy files.

Pre-defined System Roles

Administrator: Bypasses all check gates (global permission access granted).
Medical Director: High-level clinical supervisor. Can manage providers, view audit logs, run analytics, and view reports.
Doctor: Clinical operator. Assigned to families. Schedules home visits, inputs consultations, and updates patient health files.
Nurse: Clinical assistant. Records vitals, manages patient identification, and logs consultations.
Community Health Worker (CHW): Field operator. Creates family records, updates household indicators, and schedules/tracks home visits.
Billing Clerk: Financial operator. Handles payment matching, subscription updates, and billing ledger audits.
Data Manager: Administrative role. Updates geographical location definitions and reviews analytics screens.
Auditor: Compliance role. Read-only access to system audit logs, reports, and activity timelines.
Family Contact: External customer portal role. Represents a family household head.

6. Family Portal Capabilities

Users with the family-contact role are logged in directly to a custom, self-service dashboard (dashboard.family-portal) instead of the admin dashboard. This portal lets them interact directly with their allocated care team and manages their billing.

Core Portal Workflows

Book Home Visits: Requests a new check-up visit from their assigned doctor. Automatically schedules the visit and triggers a VisitRequested notification to the practitioner.
Message Practitioner: Direct message form that logs queries and pushes a DoctorContacted alert to the doctor.
Mobile Money Payment: Pushes transaction references (MTN, Airtel, Zamtel) and receipts for review. Triggers a PaymentSubmitted notification to the billing team.
Refill Request: Pushes a request for specific medications for family members. Notifies the doctor via RefillRequested notification.
Lifestyle Survey: Submits answers about water supply, sanitation, and alcohol use. Updates the family model directly, triggering an automated score and risk-level recalculation.