Patient Management System

A microservices-based patient management system built with Spring Boot, implementing modern distributed architecture patterns including REST APIs, gRPC, event-driven communication, and API Gateway routing.

📋 Table of Contents

• Overview
• Architecture
• Services
• Technology Stack
• Prerequisites
• Getting Started
• API Documentation
• Development
• Deployment
• Testing
• Future Improvements

🎯 Overview

The Patient Management System is a distributed microservices application designed to handle patient data, authentication, billing, and analytics. The system follows microservices best practices with service separation, event-driven communication, and centralized API gateway routing.

Key Features

• Patient Management: CRUD operations for patient records
• Authentication & Authorization: JWT-based authentication with role-based access
• Billing Integration: gRPC-based billing account creation
• Event-Driven Analytics: Real-time event processing via Kafka
• API Gateway: Centralized routing and JWT validation
• OpenAPI Documentation: Swagger/OpenAPI documentation for all REST services

🏗️ Architecture

System Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         Client Applications                      │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ HTTP/REST
                             │
                    ┌────────▼────────┐
                    │   API Gateway   │
                    │  (Port: 4004)   │
                    │ Spring Cloud    │
                    │    Gateway      │
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        │                    │                    │
┌───────▼───────┐   ┌────────▼────────┐   ┌───────▼───────┐
│ Auth Service │   │ Patient Service │   │Billing Service│
│ (Port: 4005) │   │  (Port: 4000)   │   │ (Port: 4001) │
│              │   │                 │   │  gRPC: 9001   │
│ - Login      │   │ - CRUD Patients │   │               │
│ - Validate   │   │ - PostgreSQL    │   │ - gRPC Server │
│ - JWT        │   │                 │   │               │
│ - PostgreSQL │   │                 │   │               │
└──────────────┘   └────────┬────────┘   └───────▲───────┘
                            │                    │
                            │ gRPC               │
                            │                    │
                            │                    │
                    ┌───────▼────────────────────┘
                    │   Kafka Message Broker     │
                    │   (Topic: patient)        │
                    └───────┬────────────────────┘
                            │
                            │ Event Consumption
                            │
                    ┌───────▼────────┐
                    │Analytics Service│
                    │  (Port: 4002)   │
                    │                 │
                    │ - Event Consumer│
                    │ - Analytics     │
                    └─────────────────┘

Communication Patterns

1. Synchronous REST: Client ↔ API Gateway ↔ Services
2. Synchronous gRPC: Patient Service ↔ Billing Service
3. Asynchronous Events: Patient Service → Kafka → Analytics Service
4. JWT Validation: API Gateway → Auth Service

Data Flow Example: Patient Creation

1. Client → API Gateway (POST /api/patients)
2. API Gateway → Auth Service (JWT Validation)
3. API Gateway → Patient Service (Create Patient)
4. Patient Service → PostgreSQL (Save Patient)
5. Patient Service → Billing Service (gRPC - Create Billing Account)
6. Patient Service → Kafka (Publish Patient Event)
7. Analytics Service ← Kafka (Consume Event)

🔧 Services

1. API Gateway (api-gateway)

• Port: 4004
• Technology: Spring Cloud Gateway (WebFlux)
• Responsibilities:
  • Route requests to appropriate services
  • JWT token validation via Auth Service
  • API documentation aggregation
• Routes:
  • /auth/** → Auth Service
  • /api/patients/** → Patient Service (with JWT validation)
  • /api-docs/patients → Patient Service Swagger
  • /api-docs/auth → Auth Service Swagger

2. Auth Service (auth-service)

• Port: 4005
• Technology: Spring Boot, Spring Security, JWT
• Database: PostgreSQL
• Responsibilities:
  • User authentication (login)
  • JWT token generation and validation
  • User management
• Endpoints:
  • POST /login - Authenticate user and generate JWT
  • GET /validate - Validate JWT token

3. Patient Service (patient-service)

• Port: 4000
• Technology: Spring Boot, Spring Data JPA
• Database: PostgreSQL
• Responsibilities:
  • Patient CRUD operations
  • Integration with Billing Service (gRPC)
  • Publishing patient events to Kafka
• Endpoints:
  • GET /patients - Get all patients
  • POST /patients - Create new patient
  • PUT /patients/{id} - Update patient
  • DELETE /patients/{id} - Delete patient

4. Billing Service (billing-service)

• Port: 4001 (HTTP), 9001 (gRPC)
• Technology: Spring Boot, gRPC
• Responsibilities:
  • Billing account management
  • gRPC service for billing operations
• gRPC Service:
  • CreateBillingAccount - Create billing account for patient

5. Analytics Service (analytics-service)

• Port: 4002
• Technology: Spring Boot, Spring Kafka
• Responsibilities:
  • Consume patient events from Kafka
  • Process and analyze patient data
  • Real-time analytics

🛠️ Technology Stack

Core Technologies

• Java: 21
• Spring Boot: 3.5.7
• Spring Cloud: 2025.0.0
• Maven: Build tool

Frameworks & Libraries

• Spring Cloud Gateway: API Gateway
• Spring Security: Authentication & Authorization
• Spring Data JPA: Database access
• gRPC: Inter-service communication
• Apache Kafka: Event streaming
• PostgreSQL: Relational database
• JWT (JJWT): Token-based authentication
• OpenAPI/Swagger: API documentation
• Protobuf: Data serialization for gRPC and events

Infrastructure

• Docker: Containerization
• PostgreSQL: Database
• Kafka: Message broker

📦 Prerequisites

Before you begin, ensure you have the following installed:

• Java 21 or higher
• Maven 3.6+
• Docker and Docker Compose (for running infrastructure)
• PostgreSQL (or use Docker)
• Apache Kafka (or use Docker)
• Git

🚀 Getting Started

1. Clone the Repository

git clone <repository-url>
cd Patient-Management

2. Start Infrastructure Services

You'll need to start PostgreSQL and Kafka. You can use Docker Compose:

# Create a docker-compose.yml in the root directory (see Deployment section)
docker-compose up -d postgres kafka

Or start them individually:

• PostgreSQL: Ensure PostgreSQL is running on port 5432
• Kafka: Ensure Kafka is running and accessible

4. Build the Project

# Build all services
mvn clean install

# Or build individual services
cd auth-service && mvn clean install
cd ../patient-service && mvn clean install
cd ../billing-service && mvn clean install
cd ../analytics-service && mvn clean install
cd ../api-gateway && mvn clean install

5. Run Services

Start services in the following order:

1. Auth Service:

   cd auth-service
   mvn spring-boot:run

2. Billing Service:

   cd billing-service
   mvn spring-boot:run

3. Analytics Service:

   cd analytics-service
   mvn spring-boot:run

4. Patient Service:

   cd patient-service
   mvn spring-boot:run

5. API Gateway:

   cd api-gateway
   mvn spring-boot:run

6. Verify Services

• API Gateway: http://localhost:4004
• Auth Service: http://localhost:4005
• Patient Service: http://localhost:4000
• Billing Service: http://localhost:4001
• Analytics Service: http://localhost:4002

📚 API Documentation

Swagger/OpenAPI Documentation

Access API documentation through the API Gateway:

• Patient Service API Docs: http://localhost:4004/api-docs/patients
• Auth Service API Docs: http://localhost:4004/api-docs/auth

API Endpoints

Authentication

Login

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

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

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Patient Management

Get All Patients (Requires JWT)

GET http://localhost:4004/api/patients
Authorization: Bearer <token>

Create Patient (Requires JWT)

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

{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "address": "123 Main St",
  "dateOfBirth": "1990-01-01",
  "registeredDate": "2024-01-01"
}

Update Patient (Requires JWT)

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

{
  "name": "John Doe Updated",
  "email": "john.doe@example.com",
  "address": "456 New St",
  "dateOfBirth": "1990-01-01",
  "registeredDate": "2024-01-01"
}

Delete Patient (Requires JWT)

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

Test Requests

Pre-configured HTTP request files are available in the api-requests/ directory:

• api-requests/auth-service/ - Auth service requests
• api-requests/patient-service/ - Patient service requests
• grpc-requests/billing-service/ - gRPC requests

💻 Development

Project Structure

Patient-Management/
├── api-gateway/          # API Gateway service
├── auth-service/         # Authentication service
├── patient-service/      # Patient management service
├── billing-service/      # Billing service (gRPC)
├── analytics-service/    # Analytics service
├── integration-tests/    # Integration tests
├── api-requests/         # HTTP request files for testing
└── grpc-requests/        # gRPC request files

Code Style

• Follow Java naming conventions
• Use meaningful variable and method names
• Add JavaDoc comments for public APIs
• Keep methods focused and single-purpose

Adding a New Service

1. Create a new Spring Boot project
2. Add service configuration in api-gateway/src/main/resources/application.yml
3. Update this README with service details
4. Add Dockerfile if needed
5. Update docker-compose.yml if using Docker

Protocol Buffers

gRPC services use Protocol Buffers for data serialization. Proto files are located in:

• patient-service/src/main/proto/
• billing-service/src/main/proto/
• analytics-service/src/main/proto/

After modifying .proto files, rebuild the project to regenerate Java classes:

mvn clean compile

🐳 Deployment

Docker

Each service includes a Dockerfile. Build and run services individually:

# Build Docker image
docker build -t patient-service:latest ./patient-service

# Run container
docker run -p 4000:4000 patient-service:latest

Docker Compose

Create a docker-compose.yml in the root directory to orchestrate all services:

version: '3.8'

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: db
      POSTGRES_USER: admin_user
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  kafka:
    image: confluentinc/cp-kafka:latest
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
    ports:
      - "9092:9092"
    depends_on:
      - zookeeper

  zookeeper:
    image: confluentinc/cp-zookeeper:latest
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000
    ports:
      - "2181:2181"

  # Add your services here...

volumes:
  postgres_data:

🧪 Testing

Unit Tests

Run unit tests for each service:

cd <service-name>
mvn test

Integration Tests

Integration tests are located in the integration-tests/ module:

cd integration-tests
mvn test

Manual Testing

Use the HTTP request files in api-requests/ directory or tools like:

• Postman
• cURL
• REST Client (VS Code extension)

🔮 Future Improvements

High Priority

• Add comprehensive unit and integration tests
• Implement database migrations (Flyway/Liquibase)
• Add distributed tracing (Zipkin/Jaeger)
• Implement circuit breakers for resilience
• Add health checks and metrics (Actuator, Prometheus)
• Externalize configuration (Config Server)
• Add service discovery (Eureka/Consul)

Medium Priority

• Implement API versioning
• Add rate limiting
• Implement caching strategies
• Add correlation IDs for request tracking
• Create parent POM for dependency management
• Add comprehensive error handling
• Implement retry mechanisms

Low Priority

• Add CI/CD pipeline (GitHub Actions/Jenkins)
• Kubernetes deployment manifests
• Performance testing and optimization
• Security enhancements (OAuth2, RBAC)
• API documentation improvements
• Monitoring dashboards (Grafana)

Note: This is a development project. For production deployment, ensure proper security configurations, environment variable management, and infrastructure setup.