Grand-Climax/Hospital-Referral-System

A digital infrastructure backend for the Ethiopian healthcare ecosystem. Orchestrates complex patient referrals, enforces role-based security, and maintains immutable audit trails of the patient journey. # 🏥 Hospital Referral Hub - Backend A mission-critical digital infrastructure for standardized patient referrals within the Ethiopian healthcare ecosystem. This backend service orchestrates complex referral workflows, enforces granular role-based security, and maintains an immutable audit trail of the patient journey. --- ## 🏗️ Core Architecture The system is built on **Clean Architecture** principles, ensuring a strict separation of concerns and high testability. - **Domain Layer**: Pure business entities and interface definitions. - **UseCase Layer**: Orchestration of business logic and state transitions. - **Repository Layer**: Data persistence (PostgreSQL) and caching (Redis) abstractions. - **Delivery Layer**: RESTful API implementation using the Gin framework. ### State-Driven Workflows At its heart, the system manages a robust **Referral State Machine**: `PENDING` → `REVIEWING` → `ACCEPTED/REJECTED` → `COMPLETED` --- ## ✨ Key Features - **🔐 Granular RBAC**: 8+ distinct healthcare roles (Doctors, Specialists, Admins, Liaisons, etc.) with a strictly enforced permission matrix. - **⚡ Dual-Layer Auth**: JWT-based authentication with high-performance session mirroring in Redis for sub-millisecond validation. - **📂 State Machine & History**: Automated tracking of every status change with an attached audit log for medical accountability. - **📡 Multi-Hospital Networking**: Intelligent routing of referrals between Tertiary, General, and Primary healthcare tiers. - **💾 Attachment Handling**: Support for medical documents, images, and DICOM files linked to clinical cases. - **📊 Real-time Audit**: Immutable logs capturing WHO, WHAT, and WHEN for every critical system interaction. - **🧠 ML-Powered Triage**: Integration-ready structures for machine learning predictions on patient severity and scheduling urgency. - **📅 Dynamic Capacity**: Automated scheduling service with configurable buffers, aging factors, and overbook management. --- ## 🛠️ Technical Stac …