Skip to content

Chiru-5/Patient-Management

BranchesTags

Repository files navigation

🏥 Patient Management System

A production-ready, microservices-based healthcare backend application for managing patient records, billing, authentication, and analytics — built with Java, Spring Boot, Kafka, gRPC, and Docker.

📑 Table of Contents

Overview

The Patient Management System is a backend microservices architecture designed for healthcare applications. It manages patient records and healthcare workflows through a set of loosely coupled, independently deployable services.

The system demonstrates modern backend patterns including:

  • REST API exposure via an API Gateway
  • Synchronous inter-service communication using gRPC
  • Asynchronous event streaming via Apache Kafka
  • Secure authentication with JWT tokens
  • Cloud-ready deployment using Docker and AWS LocalStack
  • Infrastructure as Code with AWS CloudFormation

Architecture

                          ┌─────────────────────────────────────┐
                          │             CLIENT / UI              │
                          └──────────────────┬──────────────────┘
                                             │ HTTP Requests
                                             ▼
                          ┌─────────────────────────────────────┐
                          │            API GATEWAY               │
                          │       (Spring Cloud Gateway)         │
                          │  - Route requests to services        │
                          │  - JWT validation / Auth filter      │
                          └──┬───────────────┬──────────────────┘
                             │               │
              ┌──────────────▼──┐       ┌────▼──────────────┐
              │  AUTH SERVICE   │       │  PATIENT SERVICE   │
              │ - Login / Token │       │ - CRUD operations  │
              │ - JWT generation│       │ - PostgreSQL DB     │
              └─────────────────┘       └────────┬───────────┘
                                                 │ gRPC Call
                                        ┌────────▼───────────┐
                                        │  BILLING SERVICE    │
                                        │ - Billing account   │
                                        │   creation on new   │
                                        │   patient signup    │
                                        └────────┬────────────┘
                                                 │ Kafka Event
                                        ┌────────▼────────────┐
                                        │  ANALYTICS SERVICE   │
                                        │ - Consumes Kafka     │
                                        │   events             │
                                        │ - Processes patient  │
                                        │   analytics data     │
                                        └─────────────────────┘

Tech Stack

Layer Technology Purpose
Language Java 17+ Core development language
Framework Spring Boot Microservice application framework
API Gateway Spring Cloud Gateway Single entry point, routing, auth filter
REST Communication Spring MVC / REST Synchronous client-facing APIs
gRPC Communication gRPC + Protocol Buffers Internal service-to-service sync calls
Async Messaging Apache Kafka Event-driven inter-service communication
Authentication Spring Security + JWT Stateless token-based auth
Database PostgreSQL Persistent relational data storage
Containerization Docker Container packaging and orchestration
Cloud Emulation LocalStack AWS service emulation for local dev
Infrastructure as Code AWS CloudFormation Infrastructure provisioning templates
Build Tool Maven Dependency management and build lifecycle
Testing Integration Tests module End-to-end service validation

Microservices

The system is composed of 5 core services, each with a dedicated responsibility:

Service Port Responsibility
api-gateway 4004 Routes all incoming HTTP requests; validates JWT tokens
auth-service 4005 User login, JWT token generation and validation
patient-service 4000 Full CRUD operations for patient records
billing-service 4001 Creates and manages billing accounts via gRPC
analytics-service 4002 Consumes Kafka events for analytics processing

Project Structure

Patient-Management/
│
├── api-gateway/                    # Spring Cloud Gateway
│   ├── src/
│   │   └── main/java/com/pm/apigateway/
│   │       ├── config/             # Route and security config
│   │       └── filter/             # JWT auth filter
│   ├── Dockerfile
│   └── pom.xml
│
├── auth-service/                   # Authentication microservice
│   ├── src/
│   │   └── main/java/com/pm/authservice/
│   │       ├── controller/         # Auth REST endpoints
│   │       ├── service/            # JWT logic
│   │       └── model/              # User/credentials model
│   ├── Dockerfile
│   └── pom.xml
│
├── patient-service/                # Core patient data service
│   ├── src/
│   │   └── main/java/com/pm/patientservice/
│   │       ├── controller/         # REST API controllers
│   │       ├── service/            # Business logic
│   │       ├── repository/         # JPA data access layer
│   │       ├── model/              # Patient entity
│   │       ├── dto/                # Request/Response DTOs
│   │       └── grpc/               # gRPC client (calls billing-service)
│   ├── Dockerfile
│   └── pom.xml
│
├── billing-service/                # Billing microservice (gRPC server)
│   ├── src/
│   │   └── main/java/com/pm/billingservice/
│   │       ├── grpc/               # gRPC server implementation
│   │       └── service/            # Billing business logic
│   ├── Dockerfile
│   └── pom.xml
│
├── analytics-service/              # Analytics event consumer
│   ├── src/
│   │   └── main/java/com/pm/analyticsservice/
│   │       ├── kafka/              # Kafka consumer
│   │       └── service/            # Analytics processing
│   ├── Dockerfile
│   └── pom.xml
│
├── infrastructure/                 # AWS CloudFormation templates
│   └── *.yaml / *.json             # IaC stack definitions
│
├── integration-tests/              # End-to-end integration test suite
│   └── src/test/
│
├── api-requests/                   # HTTP request files (REST client)
│   └── *.http
│
├── grpc-requests/
│   └── billing-service/            # gRPC test request files
│
├── .gitignore
└── README.md

System Flow

1. Patient Registration Flow

Client
  │
  │  POST /patients  (with JWT token)
  ▼
API Gateway
  │  Validates JWT → routes to patient-service
  ▼
Patient Service
  │  Saves patient to PostgreSQL
  │
  ├──── gRPC Call ────────────────────────────────────┐
  │                                                   ▼
  │                                         Billing Service
  │                                         Creates billing account
  │                                         for new patient
  │
  ├──── Kafka Event (PATIENT_CREATED) ────────────────┐
  │                                                   ▼
  │                                         Analytics Service
  │                                         Processes and records event
  ▼
Client  ←  201 Created (Patient Object)

2. Authentication Flow

Client
  │
  │  POST /auth/login  {email, password}
  ▼
API Gateway
  │  Routes to auth-service (no JWT required)
  ▼
Auth Service
  │  Validates credentials
  │  Generates signed JWT token
  ▼
Client  ←  200 OK  { token: "eyJ..." }

─────────────────────────────────────────────────────────

Subsequent Requests:
Client
  │  Authorization: Bearer <token>
  ▼
API Gateway
  │  Extracts + validates JWT signature
  │  Forwards request if valid
  ▼
Target Service  →  Response  →  Client

3. Inter-Service Communication Map

patient-service  ──── gRPC (sync) ────►  billing-service
patient-service  ──── Kafka (async) ──►  analytics-service
api-gateway      ──── HTTP route ──────► patient-service
api-gateway      ──── HTTP route ──────► auth-service
api-gateway      ──── JWT Filter ──────► (all secured routes)

API Endpoints

All requests go through the API Gateway (default: http://localhost:4004).
Secured endpoints require the Authorization: Bearer <token> header.

Auth Service

Method Endpoint Auth Required Description
POST /auth/login ❌ Authenticate and receive JWT token

Patient Service

Method Endpoint Auth Required Description
GET /patients ✅ Get all patients
GET /patients/{id} ✅ Get a patient by ID
POST /patients ✅ Create a new patient
PUT /patients/{id} ✅ Update patient details
DELETE /patients/{id} ✅ Delete a patient

Create / Update Patient — Request Body

{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "address": "123 Main Street, New York",
  "dateOfBirth": "1990-05-15"
}

Patient Response Object

{
  "id": "a3f4c1d2-...",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "address": "123 Main Street, New York",
  "dateOfBirth": "1990-05-15"
}

Database Schema

Patient Table (patient_service DB)

Column Type Constraints Description
id UUID PRIMARY KEY Unique patient identifier (auto-generated)
name VARCHAR NOT NULL Full name of the patient
email VARCHAR NOT NULL, UNIQUE Patient email address
address VARCHAR NOT NULL Patient residential address
date_of_birth DATE NOT NULL Patient date of birth

Inter-Service Communication

gRPC — Patient Service → Billing Service

When a new patient is created, patient-service makes a synchronous gRPC call to billing-service to automatically create a billing account.

  • Proto definitions are located in grpc-requests/billing-service/
  • gRPC ensures strong typing and low-latency communication between services
patient-service (gRPC client)
        │
        │   BillingRequest { patientId, patientName, patientEmail }
        ▼
billing-service (gRPC server)
        │
        │   BillingResponse { accountId, status }
        ▼
patient-service (receives response)

Kafka — Patient Service → Analytics Service

Patient events are published to a Kafka topic for asynchronous consumption by analytics-service.

  • Topic: patient (or similar, e.g., patient-events)
  • Producer: patient-service publishes PATIENT_CREATED events
  • Consumer: analytics-service reads and processes those events
patient-service  ──► Kafka Topic: "patient"  ──► analytics-service
   (Producer)                                       (Consumer)

Infrastructure

The infrastructure/ directory contains AWS CloudFormation templates that provision the system's cloud resources, emulated locally via LocalStack.

Resources Provisioned

Resource Purpose
Amazon MSK / Kafka Managed Kafka cluster for event streaming
Amazon RDS / PostgreSQL Managed relational database for patient data
ECS / EKS Container orchestration for microservices
VPC / Subnets Network isolation and security groups
IAM Roles Service-level access policies

LocalStack Setup

LocalStack emulates AWS services locally so you can develop and test without a real AWS account.

# Start LocalStack (requires Docker)
docker run --rm -p 4566:4566 localstack/localstack

# Deploy CloudFormation stack
aws --endpoint-url=http://localhost:4566 cloudformation deploy \
  --template-file infrastructure/stack.yaml \
  --stack-name patient-management

Getting Started

Prerequisites

Ensure the following are installed:

  • Java 17+
  • Maven 3.8+
  • Docker & Docker Compose
  • AWS CLI (for LocalStack interactions)

Clone the Repository

git clone https://github.com/Chiru-5/Patient-Management.git
cd Patient-Management

Build All Services

# From the root directory, build each service
mvn clean install -f patient-service/pom.xml
mvn clean install -f billing-service/pom.xml
mvn clean install -f auth-service/pom.xml
mvn clean install -f analytics-service/pom.xml
mvn clean install -f api-gateway/pom.xml

Run with Docker Compose

docker compose up --build

This will start:

Service URL
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
PostgreSQL localhost:5432
Kafka localhost:9092

Running Tests

Integration Tests

The integration-tests/ module contains end-to-end tests that validate inter-service communication.

mvn test -f integration-tests/pom.xml

REST API Testing

Pre-written HTTP request files are available in api-requests/ and can be run using IntelliJ HTTP Client or VS Code REST Client.

api-requests/
├── patients.http       # CRUD requests for patient-service
└── auth.http           # Login and token requests

gRPC Testing

Test files for the billing service gRPC endpoints are in grpc-requests/billing-service/.

Environment Variables

Each service is configured via environment variables (typically injected via Docker or application.properties).

Variable Service Description
SPRING_DATASOURCE_URL patient-service PostgreSQL connection URL
SPRING_DATASOURCE_USERNAME patient-service DB username
SPRING_DATASOURCE_PASSWORD patient-service DB password
JWT_SECRET auth-service, api-gateway Secret key for JWT signing/validation
SPRING_KAFKA_BOOTSTRAP_SERVERS patient-service, analytics-service Kafka broker address
BILLING_SERVICE_ADDRESS patient-service gRPC address for billing-service
AUTH_SERVICE_URL api-gateway URL for auth-service routing

Contributing

  1. Fork the repository
  2. Create your feature branch: git checkout -b feature/your-feature
  3. Commit your changes: git commit -m 'Add your feature'
  4. Push to the branch: git push origin feature/your-feature
  5. Open a Pull Request

License

This project is open source and available under the MIT License.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages