🏥 HealthSaga: Distributed Healthcare Architecture

📖 About

HealthSaga is a highly scalable, event-driven microservices ecosystem designed for modern healthcare management. The system seamlessly integrates a high-performance API Gateway, multiple domain-specific microservices, and an AI-powered medical triage engine.

Built strictly on Domain-Driven Design (DDD) principles, the project showcases enterprise-grade patterns such as the Saga Pattern for distributed transactions, real-time event streaming, and advanced security mechanisms including Zero-Trust IAM and Data Masking.

🛠 Tech Stack

API Gateway (The Entry Point)

• Core: Golang
• Features: WAF Middleware, Data Masking, Dynamic Load Balancing, Intelligent Cost-Based Router.

Core Microservices (Business Logic)

• Core: Java 17, Spring Boot 3
• Architecture: Hexagonal Architecture, Domain-Driven Design (DDD).
• Services: Patient, Appointment, Billing, Audit, Notification.

Machine Learning Engine (Triage)

• Core: Python 3.10, FastAPI
• Model: Tiny ML Prediction Model (based on Kaggle Patient Dataset).

Infrastructure & Data

• Event Streaming: Apache Kafka (Outbox Pattern & Event Choreography).
• Databases: PostgreSQL (Relational), MongoDB (NoSQL).
• Caching: Redis (High-Performance Caching).
• IAM: Keycloak (Identity & Access Management).
• DevOps: Docker, Docker Compose.
• Logging: Grafana Loki (Centralized log aggregation for all microservices)

Observability & Monitoring

• Metrics Collection: Prometheus (Scraping Spring Boot Actuator endpoints).
• Visualization: Grafana (Dynamic dashboards for system health, JVM metrics, and resource utilization).
• Centralized Logging: Grafana Loki with Promtail (Aggregating container logs from Docker for unified troubleshooting).
• Distributed Tracing: OpenTelemetry API/SDK wrapper wired across the Go Gateway, Spring Boot services, and FastAPI node, exporting spans to a centralized Jaeger collector via OTLP/HTTP.

✨ Technical Highlights & Features

🧩 Enterprise Microservices Architecture

• Domain-Driven Design (DDD): Deep separation of concerns. The Patient Service utilizes Hexagonal Architecture (Ports and Adapters) to isolate domain logic from infrastructure.
• Distributed Transactions: Full implementation of the Saga Pattern. Orchestrates complex admission processes (Patient Creation ➔ Appointment Scheduling ➔ Triage Prediction) with automated Compensating Transactions (Rollbacks) if any step fails.

🛡️ Advanced API Gateway (Golang)

• Custom WAF & Security: Built-in Web Application Firewall middleware and on-the-fly Data Masking for sensitive PII/PHI.
• Smart Routing: Intelligent Cost-Based Router and custom Load Balancing algorithm with active Health Checks.

⚡ Event-Driven & High Performance

• Kafka Cluster: Decouples core services from side-effects. Appointment creations emit events consumed asynchronously by Audit, Billing, and Notification services.
• Redis Integration: High-performance caching layers to reduce database hits on frequently accessed medical records.

🧠 AI Medical Triage

• FastAPI ML Endpoint: An isolated microservice evaluating patient vitals (Age, Heart Rate, Blood Pressure, Temperature) to predict urgency, deeply integrated into the Saga admission flow.

📊 Full Observability Stack

• Real-time Metrics: Deep integration with Spring Boot Actuator to expose JVM internals, HikariCP connection pools, and real-time HTTP metrics.
• Centralized Dashboards: Grafana connected to Prometheus via a secure Docker bridge network, visualizing live traffic, resource utilization, and system health.

🚀 Quick Start

1. Prerequisites

• Docker & Docker Compose
• Go 1.21+
• Java 17 (JDK)
• Python 3.10+

2. Spin Up Infrastructure

Start the required databases, Kafka cluster, Keycloak, and Redis using Docker Compose:

docker-compose up -d

3. Build & Run Services

You can run the entire ecosystem via Docker, or individually for development:

API Gateway (Golang):

cd api-gateway
go run main.go loadbalancer.go

Patient Service (Java/Spring Boot):

cd patient-service
./mvnw spring-boot:run

Triage Service (Python/FastAPI):

cd triage-service
pip install -r requirements.txt
uvicorn api.main:app --port 8000

4. Trigger the Saga Admission Process

Send a POST request to the Gateway to initiate the Distributed Transaction:

POST http://localhost:8080/api/admission/full-process
Content-Type: application/json
Authorization: Bearer <Keycloak_Token>

{
  "name": "Israel Israeli",
  "age": 45,
  "date": "2026-06-05",
  "heart_rate": 85,
  "blood_pressure_systolic": 120,
  "temperature": 37.2
}

5. Monitor the System (Observability)

Once the ecosystem is running, access the monitoring tools:

• Prometheus: http://localhost:9090 (Check target health status)
• Grafana: http://localhost:3000 (Login: admin/admin)
  • Metrics: Use the pre-imported JVM Dashboards.
  • Logs: Navigate to Explore ➔ select Loki ➔ query {job="docker"} to view logs across all services.
• Jaeger UI: http://localhost:16686 (Analyze distributed transactions and end-to-end trace contexts across Golang, Java, and Python).

📁 Project Structure

📦 HealthSaga
 ├── 📂 api-gateway/          # Golang Gateway, LB, WAF, Saga Orchestrator
 ├── 📂 patient-service/      # Java Spring Boot, Hexagonal Arch, MongoDB
 ├── 📂 appointment-service/  # Java Spring Boot, PostgreSQL, Kafka Producer
 ├── 📂 triage-service/       # Python FastAPI, Tiny ML Model
 ├── 📂 billing-service/      # Java Spring Boot, Kafka Consumer
 ├── 📂 audit-service/        # Java Spring Boot, Kafka Consumer
 ├── 📂 notification-service/ # Java Spring Boot, Kafka Consumer
 └── 📜 docker-compose.yml    # Infra: Postgres, Mongo, Redis, Kafka, Keycloak
 └── 📜 prometheus.yml        # Prometheus scrape configurations
 └── 📜 promtail-config.yaml  # Promtail log collection configuration

---

Developed as an advanced showcase of Distributed Systems, Zero-Trust Security, and Event-Driven Architecture.