🏥 Patient Management System

A production-grade, cloud-native microservices platform for healthcare patient management

📋 Table of Contents

Overview
Architecture
Services
Technology Stack
Key Features
Getting Started
API Reference
Inter-Service Communication
Observability & Monitoring
Cloud Infrastructure (AWS CDK)
Integration Testing
Project Structure

🌟 Overview

The Patient Management System is a fully containerized, event-driven microservices backend built with Java 21 and Spring Boot 3.4. It demonstrates real-world enterprise patterns including asynchronous messaging, synchronous RPC, API gateway routing with JWT authentication, Redis caching, distributed rate limiting, circuit breaking with fallback strategies, Prometheus metrics, and cloud-native deployment via AWS CDK with LocalStack.

This project serves as a comprehensive reference for:

Designing and implementing a microservices architecture from scratch
Applying resilience patterns (circuit breaker, retry, fallback)
Implementing event-driven communication with Apache Kafka and Protobuf
Securing a distributed system with JWT authentication at the gateway layer
Deploying to AWS using Infrastructure as Code with the CDK

🏗️ Architecture

                          ┌─────────────────────────────────────────────────────┐
                          │                   External Client                   │
                          └──────────────────────────┬──────────────────────────┘
                                                     │ HTTP :4004
                                                     ▼
                          ┌──────────────────────────────────────────────────────┐
                          │               API Gateway  (port 4004)               │
                          │   • JWT Validation Filter  • Rate Limiting (Redis)   │
                          │   • Route to Auth Service  • Route to Patient Service│
                          └──┬──────────────────────────────────────┬────────────┘
                             │ /auth/**                             │ /api/patients/**
                             ▼                                      ▼
              ┌──────────────────────────┐          ┌──────────────────────────────┐
              │   Auth Service :4005     │          │   Patient Service :4000      │
              │   • JWT login/validate   │          │   • CRUD operations          │
              │   • PostgreSQL DB        │◄─validate│   • Redis cache (10 min TTL) │
              └──────────────────────────┘          │   • Prometheus metrics       │
                                                    └───────┬──────────┬───────────┘
                                              gRPC :9001    │          │ Kafka
                                                            ▼          ▼
                                          ┌───────────────────┐  ┌───────────────────────────┐
                                          │  Billing Service  │  │     Apache Kafka Broker   │
                                          │  :4001 / :9001    │  │  Topics:                  │
                                          │  • gRPC server    │  │   patient.created         │
                                          │  • Kafka consumer │  │   patient.updated         │
                                          │    (billing-acct) │  │   billing-account         │
                                          └───────────────────┘  └──────────┬────────────────┘
                                                                            │ Consumers
                                                              ┌─────────────┼───────────────┐
                                                              ▼             ▼               ▼
                                                  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
                                                  │  Appointment │ │  Analytics   │ │   Billing    │
                                                  │  Service     │ │  Service     │ │  Service     │
                                                  │  :4003       │ │  :4002       │ │  (fallback)  │
                                                  └──────────────┘ └──────────────┘ └──────────────┘

                                                  ┌────────────────────────────────┐
                                                  │   Monitoring Stack             │
                                                  │   Prometheus :9090             │
                                                  │   Grafana :3000                │
                                                  └────────────────────────────────┘

📦 Services

Service	Port	Description
API Gateway	`4004`	Spring Cloud Gateway — JWT authentication, IP-based rate limiting, reverse proxy routing
Auth Service	`4005`	User login, JWT token issuance and validation, Spring Security + PostgreSQL
Patient Service	`4000`	Core CRUD for patients, Redis caching, Kafka producer, gRPC client
Billing Service	`4001` / `9001`	gRPC server for account creation, Kafka consumer for fallback billing events
Appointment Service	`4003`	Appointment scheduling with optimistic locking, Kafka consumer for patient cache
Analytics Service	`4002`	Event listener for patient events (extensible analytics hooks)
Infrastructure	—	AWS CDK stack defining the full cloud topology (ECS Fargate, RDS, ElastiCache, MSK)
Monitoring	`9090` / `3000`	Prometheus scraping + Grafana dashboards

🛠️ Technology Stack

Category	Technology
Language	Java 21
Framework	Spring Boot 3.4, Spring Cloud Gateway
Messaging	Apache Kafka + Protocol Buffers (Protobuf)
RPC	gRPC (grpc-java 1.69, protobuf-maven-plugin)
Caching	Redis (Spring Data Redis, `@Cacheable` with 10-min TTL)
Databases	PostgreSQL (production), H2 (integration tests)
Security	Spring Security, JWT (JJWT 0.12.6)
Resilience	Resilience4j (Circuit Breaker + Retry)
Observability	Spring Actuator, Micrometer, Prometheus, Grafana
API Docs	SpringDoc OpenAPI (Swagger UI)
Cloud / IaC	AWS CDK (Java), LocalStack
Testing	JUnit 5, REST Assured
Containerization	Docker (per-service Dockerfiles)

✨ Key Features

🔐 Authentication & Authorization

JWT-based auth issued by the Auth Service and validated at the gateway
Admin seed user pre-loaded via data.sql for immediate use
Token extracted from the Authorization: Bearer <token> header at every protected route

🌐 API Gateway

Single entry point for all external traffic on port 4004
JWT Validation Filter — custom GatewayFilterFactory that delegates validation to the Auth Service via WebClient
IP-based Rate Limiting — backed by Redis; limits to 5 requests/second per IP (burst capacity: 5)
Route profiles: application.yml (local Docker) and application-prod.yml (AWS ECS with service discovery)

📊 Patient Management

Full CRUD API (GET, POST, PUT, DELETE) with Swagger UI documentation
Pagination, sorting, and search (case-insensitive name search) with page metadata in the response
Bean Validation with custom validation groups (CreatePatientValidationGroup) — registeredDate is only required on creation
Redis caching on getPatients (key = page-size-sort-sortField, bypassed when a search value is active), TTL 10 minutes
AOP metrics — custom custom.redis.cache.miss Prometheus counter instrumented via a Spring AOP aspect around getPatients

⚡ Event-Driven Communication (Kafka + Protobuf)

Events are serialized using Protocol Buffers for schema-safe, binary-efficient messaging:

Topic	Producer	Consumers
`patient.created`	Patient Service	Appointment Service, Analytics Service
`patient.updated`	Patient Service	Appointment Service
`billing-account`	Patient Service (fallback)	Billing Service

When a patient is created:

Patient record saved to PostgreSQL
gRPC call to Billing Service to create a billing account
patient.created Kafka event emitted
If gRPC fails → Circuit Breaker opens → fallback sends billing-account Kafka event for async retry

🔌 gRPC Communication

Billing Service exposes a gRPC server (BillingGrpcService) on port 9001
Patient Service connects as a gRPC client (BillingServiceGrpcClient) configured via billing.service.address and billing.service.grpc.port
Contracts defined in .proto files and code-generated via protobuf-maven-plugin

🛡️ Resilience (Circuit Breaker + Retry)

@CircuitBreaker(name="billingService") — wraps the gRPC call; opens after repeated failures
@Retry(name="billingRetry") — retries transiently failed gRPC calls
Fallback — billingFallback() emits a billing-account Kafka event so billing account creation is eventually handled asynchronously
Billing Service Kafka consumer then picks this up and creates the account

📅 Appointment Service

Local CachedPatient entity updated via Kafka events — no cross-service HTTP calls needed to resolve patient names
Optimistic locking via JPA @Version on the Appointment entity to prevent concurrent update conflicts
Query by date range: findByStartTimeBetween(from, to)

📈 Monitoring

Prometheus scrapes /actuator/prometheus from the Patient Service every 5 seconds
Grafana (grafana/grafana) deployed alongside for dashboard visualization
Custom Micrometer counter custom.redis.cache.miss tracks cache miss rate

🚀 Getting Started

Prerequisites

Tool	Version
Docker & Docker Compose	Latest
Java JDK	21
Maven	3.9+

1. Clone the Repository

git clone <repository-url>
cd cloud-native-patient-management-system

2. Start Infrastructure Services

Start the required infrastructure containers (PostgreSQL, Kafka, Redis):

docker-compose up -d

Make sure Kafka, Redis, and both PostgreSQL databases are running before starting any Spring Boot service.

3. Run Services Individually (Development)

Each service is an independent Spring Boot application. Run them in this recommended order:

# 1. Auth Service
cd auth-service && ./mvnw spring-boot:run

# 2. Billing Service (must be up before Patient Service)
cd billing-service && ./mvnw spring-boot:run

# 3. Patient Service
cd patient-service && ./mvnw spring-boot:run

# 4. Appointment Service
cd appointment-service && ./mvnw spring-boot:run

# 5. Analytics Service
cd analytics-service && ./mvnw spring-boot:run

# 6. API Gateway (last — depends on all services)
cd api-gateway && ./mvnw spring-boot:run

4. Seed Database User

The Auth Service's data.sql automatically seeds a test admin user on startup:

Field	Value
Email	`testuser@test.com`
Password	`password123`
Role	`ADMIN`

📡 API Reference

All requests to protected endpoints must go through the API Gateway on port 4004.

Authentication

Login — Get a JWT Token

POST http://localhost:4004/auth/login
Content-Type: application/json

{
  "email": "testuser@test.com",
  "password": "password123"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiJ9..."
}

Validate Token

GET http://localhost:4004/auth/validate
Authorization: Bearer <token>

Patient Endpoints

All patient endpoints require a valid Authorization: Bearer <token> header.

Get Patients (Paginated)

GET http://localhost:4004/api/patients?page=1&size=10&sort=asc&sortField=name&searchValue=
Authorization: Bearer <token>

Query Parameters:

Parameter	Default	Description
`page`	`1`	Page number (1-indexed)
`size`	`10`	Page size
`sort`	`asc`	Sort direction (`asc` \| `desc`)
`sortField`	`name`	Field to sort by
`searchValue`	`""`	Case-insensitive name search

Response:

{
  "patients": [
    {
      "id": "uuid",
      "name": "John Doe",
      "email": "john@example.com",
      "address": "123 Main Street",
      "dateOfBirth": "1990-01-15",
      "registeredDate": "2024-01-01"
    }
  ],
  "currentPage": 1,
  "pageSize": 10,
  "totalPages": 5,
  "totalElements": 47
}

Create Patient

POST http://localhost:4004/api/patients
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "address": "456 Oak Avenue",
  "dateOfBirth": "1985-06-22",
  "registeredDate": "2025-01-10"
}

On creation, a billing account is automatically provisioned via gRPC to the Billing Service, and a patient.created event is published to Kafka.

Update Patient

PUT http://localhost:4004/api/patients/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Jane Smith Updated",
  "email": "jane.updated@example.com",
  "address": "789 Pine Road",
  "dateOfBirth": "1985-06-22"
}

Delete Patient

DELETE http://localhost:4004/api/patients/{id}
Authorization: Bearer <token>

Appointment Endpoints

Get Appointments by Date Range

GET http://localhost:4003/appointments?from=2025-01-01T00:00:00&to=2025-12-31T23:59:59

Swagger / OpenAPI Docs

Service	URL
Patient Service	`http://localhost:4000/swagger-ui.html`
Auth Service	`http://localhost:4005/swagger-ui.html`
Via Gateway (aggregated)	`http://localhost:4004/api-docs/patients`

🔗 Inter-Service Communication

gRPC — Patient → Billing (Synchronous)

When a new patient is created, the Patient Service makes a synchronous gRPC call to provision a billing account:

Patient Service  ──gRPC──►  Billing Service
                            createBillingAccount(patientId, name, email)
                            ◄──────────────────
                            BillingResponse { accountId, status }

Failure Scenario (Circuit Breaker):

Patient Service  ──gRPC──►  Billing Service (DOWN)
                            ▼ Circuit Opens
Patient Service ──Kafka──►  billing-account topic
                            ▼
                Billing Service Kafka Consumer picks up the event
                and creates the billing account asynchronously

Kafka — Event-Driven (Asynchronous)

Event	Schema (Protobuf)	Produced By	Consumed By
`patient.created`	`PatientEvent { patientId, name, email }`	Patient Service	Appointment Service, Analytics Service
`patient.updated`	`PatientEvent { patientId, name, email }`	Patient Service	Appointment Service
`billing-account`	`BillingAccountEvent { patientId, name, email, eventType }`	Patient Service (fallback)	Billing Service

The Appointment Service maintains a local CachedPatient table — it subscribes to patient.created and patient.updated events and upserts the local cache so that appointment queries can resolve patient names without any synchronous API call.

📊 Observability & Monitoring

Prometheus Metrics

The Patient Service exposes metrics at /actuator/prometheus. Prometheus is configured to scrape this endpoint every 5 seconds.

Metric	Description
Standard Spring Boot metrics	JVM, HTTP requests, DB pool, etc.
`custom.redis.cache.miss`	Custom AOP counter — tracks how often the `getPatients` service method bypasses the Redis cache

Grafana Dashboard

Grafana runs on port 3000. Connect it to Prometheus (http://prometheus:9090) and import dashboards for:

JVM health (heap, GC, threads)
HTTP request rates and latencies
Custom cache miss counters

Health Checks

Spring Boot Actuator health endpoints are available on each service at /actuator/health.

☁️ Cloud Infrastructure (AWS CDK)

The infrastructure/ module contains a Java-based AWS CDK stack (LocalStack.java) that provisions the entire system to AWS (and locally via LocalStack).

Resources Provisioned

Resource	AWS Service	Config
VPC	Amazon VPC	2 Availability Zones
Auth DB	Amazon RDS PostgreSQL 17.2	`db.t2.micro`, auto-generated secret
Patient DB	Amazon RDS PostgreSQL 17.2	`db.t2.micro`, auto-generated secret
Kafka Cluster	Amazon MSK	`kafka.m5.xlarge`, 2 broker nodes
Redis Cluster	Amazon ElastiCache	`cache.t2.micro`, 1 node
ECS Cluster	Amazon ECS	Fargate, Cloud Map service discovery
API Gateway	ECS Fargate + ALB	Public-facing, port 4004
Auth Service	ECS Fargate	Private, port 4005
Patient Service	ECS Fargate	Private, port 4000
Billing Service	ECS Fargate	Private, ports 4001 + 9001
Analytics Service	ECS Fargate	Private, port 4002
Prometheus	ECS Fargate	Private, port 9090
Grafana	ECS Fargate + ALB	Public-facing, port 3000

Deployment with LocalStack

cd infrastructure
./localstack-deploy.sh

Requires LocalStack and the AWS CDK to be installed.

Service Discovery

In production (ECS), services communicate via AWS Cloud Map private DNS:

auth-service.patient-management.local:4005
patient-service.patient-management.local:4000
billing-service.patient-management.local:9001

🧪 Integration Testing

The integration-tests/ module contains end-to-end tests powered by REST Assured that run against the full stack.

Run Integration Tests

# Start all services first (API Gateway must be reachable on :4004)
cd integration-tests
./mvnw test

Test Coverage

Test	Description
`shouldReturnPatientsWithValidToken`	Logs in, gets a JWT, calls `GET /api/patients`, asserts 200 with patients list
`shouldReturn429AfterLimitExceeded`	Fires 10 rapid requests and asserts at least 1 returns HTTP 429 (rate limit enforced)
`AuthIntegrationTest`	Auth flow validation tests

📁 Project Structure

cloud-native-patient-management-system/
│
├── api-gateway/                    # Spring Cloud Gateway
│   └── src/main/
│       ├── java/com/pm/apigateway/
│       │   ├── config/RateLimiterConfig.java       # IP-based key resolver
│       │   └── filter/JwtValidationGatewayFilterFactory.java
│       └── resources/
│           ├── application.yml                     # Local Docker routes
│           └── application-prod.yml                # AWS ECS routes
│
├── auth-service/                   # JWT Authentication
│   └── src/main/java/com/pm/authservice/
│       ├── controller/AuthController.java          # POST /login, GET /validate
│       ├── service/AuthService.java
│       ├── service/UserService.java
│       └── util/JwtUtil.java
│
├── patient-service/                # Core Patient Domain
│   └── src/main/java/com/pm/patientservice/
│       ├── aspects/PatientServiceMetrics.java      # AOP Prometheus counter
│       ├── cache/RedisCacheConfig.java             # Redis TTL & serialization
│       ├── controller/PatientController.java       # CRUD REST endpoints
│       ├── grpc/BillingServiceGrpcClient.java      # gRPC client + circuit breaker
│       ├── kafka/KafkaProducer.java                # Protobuf event publisher
│       ├── model/Patient.java
│       └── service/PatientService.java
│
├── billing-service/                # Billing Account Management
│   └── src/main/java/com/pm/billingservice/
│       ├── grpc/BillingGrpcService.java            # gRPC server implementation
│       └── kafka/KafkaConsumer.java                # Fallback billing event consumer
│
├── appointment-service/            # Appointment Scheduling
│   └── src/main/java/com/pm/appointmentservice/
│       ├── controller/AppointmentController.java
│       ├── entity/Appointment.java                 # @Version optimistic locking
│       ├── entity/CachedPatient.java               # Local patient data cache
│       ├── kafka/KafkaConsumer.java                # Syncs patient cache from events
│       └── service/AppointmentService.java
│
├── analytics-service/              # Event Analytics
│   └── src/main/java/com/pm/analyticsservice/
│       └── kafka/KafkaConsumer.java                # Patient event subscriber
│
├── infrastructure/                 # AWS CDK Stack (Java)
│   └── src/main/java/com/pm/stack/LocalStack.java # Full AWS topology definition
│
├── monitoring/
│   ├── prometheus.yml              # Scrape config for patient-service
│   └── prometheus-prod.yml        # Production scrape config
│
├── integration-tests/              # End-to-End Tests (REST Assured)
│   └── src/test/java/
│       ├── PatientIntegrationTest.java
│       └── AuthIntegrationTest.java
│
├── api-requests/                   # HTTP request files (IntelliJ / VS Code)
│   ├── auth-service/               # login.http, validate.http
│   ├── patient-service/            # create, update, delete, get patients
│   └── appointment-service/        # get-appointments-by-date-range.http
│
└── grpc-requests/
    └── billing-service/            # gRPC test requests

🔧 Environment Variables Reference

Auth Service

Variable	Example	Description
`SPRING_DATASOURCE_URL`	`jdbc:postgresql://auth-service-db:5432/db`	PostgreSQL connection
`SPRING_DATASOURCE_USERNAME`	`admin_user`	DB username
`SPRING_DATASOURCE_PASSWORD`	`password`	DB password
`SPRING_JPA_HIBERNATE_DDL_AUTO`	`update`	Schema management
`SPRING_SQL_INIT_MODE`	`always`	Run `data.sql` on startup

Patient Service

Variable	Example	Description
`SPRING_DATASOURCE_URL`	`jdbc:postgresql://patient-service-db:5432/db`	PostgreSQL connection
`SPRING_DATASOURCE_USERNAME`	`admin_user`	DB username
`SPRING_DATASOURCE_PASSWORD`	`password`	DB password
`SPRING_KAFKA_BOOTSTRAP_SERVERS`	`kafka:9092`	Kafka broker address
`BILLING_SERVICE_ADDRESS`	`billing-service`	gRPC host for Billing Service
`BILLING_SERVICE_GRPC_PORT`	`9001`	gRPC port for Billing Service
`SPRING_JPA_HIBERNATE_DDL_AUTO`	`update`	Schema management
`SPRING_SQL_INIT_MODE`	`always`	Run `data.sql` on startup

API Gateway

Variable	Example	Description
`SPRING_PROFILES_ACTIVE`	`prod`	Activate production route config
`AUTH_SERVICE_URL`	`http://auth-service:4005`	Auth Service URL for JWT validation
`REDIS_HOST`	`redis`	Redis hostname for rate limiting
`REDIS_PORT`	`6379`	Redis port

📝 License

This project is for educational purposes. Original course material by Chris Blakely available on his YouTube channel.

Made with ❤️ using Java, Spring Boot, and modern distributed systems patterns

Name		Name	Last commit message	Last commit date
analytics-service		analytics-service
api-gateway		api-gateway
api-requests		api-requests
appointment-service		appointment-service
auth-service		auth-service
billing-service		billing-service
grpc-requests/billing-service		grpc-requests/billing-service
infrastructure		infrastructure
integration-tests		integration-tests
monitoring		monitoring
patient-service		patient-service
volumes		volumes
.gitignore		.gitignore
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation