🏥 Patient Management System

✨ Features

📋 Table of Contents

🏗️ Architecture

┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────┐
│ Client │─────▶│ Controller │─────▶│ Service │─────▶│ Repo │
│ (Swagger/ │ │ (REST API) │ │ (Business │ │ (JPA) │
│ Postman) │◀─────│ │◀─────│ Logic) │◀─────│ │
└─────────────┘ └──────────────┘ └─────────────┘ └──────────┘
 │ │
 ▼ ▼
 ┌──────────────┐ ┌──────────┐
 │ Security │ │PostgreSQL│
 │ (JWT Filter)│ │ Database │
 └──────────────┘ └──────────┘

Layered Architecture

🛠️ Tech Stack

📋 Prerequisites

🚀 Installation

1. Clone the Repository

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

2. Environment Setup

# Database Configuration
POSTGRES_DB=pms
POSTGRES_USER=pms
POSTGRES_PASSWORD=your_secure_password
# Spring Configuration
SPRING_PROFILES_ACTIVE=dev
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/pms
SPRING_DATASOURCE_USERNAME=pms
SPRING_DATASOURCE_PASSWORD=your_secure_password
# JWT Configuration
JWT_SECRET=your-256-bit-secret-key-change-this-in-production
JWT_EXPIRATION=86400000
# Server Configuration
SERVER_PORT=8080

3. Install Dependencies

mvn clean install

⚙️ Configuration

Application Properties

server:
 port: ${SERVER_PORT:8080}
spring:
 application:
 name: patient-management-system
 
 datasource:
 url: ${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/pms}
 username: ${SPRING_DATASOURCE_USERNAME:pms}
 password: ${SPRING_DATASOURCE_PASSWORD:pms}
 driver-class-name: org.postgresql.Driver
 
 jpa:
 hibernate:
 ddl-auto: validate
 show-sql: false
 properties:
 hibernate:
 format_sql: true
 dialect: org.hibernate.dialect.PostgreSQLDialect
 jdbc.lob.non_contextual_creation: true
 
 flyway:
 enabled: true
 baseline-on-migrate: true
 locations: classpath:db/migration
security:
 jwt:
 secret: ${JWT_SECRET:change-me-please}
 expiration: ${JWT_EXPIRATION:86400000}
logging:
 level:
 root: INFO
 com.example.pms: DEBUG
 org.springframework.web: INFO
 org.hibernate.SQL: DEBUG

🏃 Running the Application

Option 1: Local Development (Without Docker)

Step 1: Setup PostgreSQL

# Create database
sudo -u postgres psql
CREATE DATABASE pms;
CREATE USER pms WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE pms TO pms;
\q

Step 2: Run the Application

mvn spring-boot:run

Option 2: Docker Compose (Recommended)

# Build and start services
docker-compose up --build
# Or run in detached mode
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down

Option 3: Build JAR and Run

# Build JAR
mvn clean package -DskipTests
# Run JAR
java -jar target/patient-management-0.0.1-SNAPSHOT.jar

📚 API Documentation

Swagger UI

http://localhost:8080/swagger-ui/index.html

OpenAPI Specification

http://localhost:8080/v3/api-docs

🗄️ Database Schema

Entity Relationship Diagram

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Doctor │ │ Appointment │ │ Patient │
├─────────────────┤ ├──────────────────┤ ├─────────────────┤
│ id (PK) │◀───┐ │ id (PK) │ ┌───▶│ id (PK) │
│ first_name │ │ │ patient_id (FK) │────┘ │ first_name │
│ last_name │ └────│ doctor_id (FK) │ │ last_name │
│ email │ │ start_time │ │ email │
│ specialization │ │ end_time │ │ phone │
│ created_at │ │ notes │ │ dob │
│ updated_at │ │ status │ │ gender │
└─────────────────┘ │ created_at │ │ created_at │
 │ updated_at │ │ updated_at │
 └──────────────────┘ └─────────────────┘

Database Tables

CREATE TABLE doctors (
 id BIGSERIAL PRIMARY KEY,
 first_name VARCHAR(80) NOT NULL,
 last_name VARCHAR(80) NOT NULL,
 email VARCHAR(120) UNIQUE NOT NULL,
 specialization VARCHAR(120),
 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE patients (
 id BIGSERIAL PRIMARY KEY,
 first_name VARCHAR(80) NOT NULL,
 last_name VARCHAR(80) NOT NULL,
 email VARCHAR(120) UNIQUE,
 phone VARCHAR(30),
 dob DATE,
 gender VARCHAR(10),
 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE appointments (
 id BIGSERIAL PRIMARY KEY,
 patient_id BIGINT NOT NULL REFERENCES patients(id),
 doctor_id BIGINT NOT NULL REFERENCES doctors(id),
 start_time TIMESTAMP NOT NULL,
 end_time TIMESTAMP NOT NULL,
 notes TEXT,
 status VARCHAR(20) DEFAULT 'SCHEDULED',
 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 
 CONSTRAINT fk_patient FOREIGN KEY (patient_id) REFERENCES patients(id) ON DELETE CASCADE,
 CONSTRAINT fk_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id) ON DELETE CASCADE
);
CREATE INDEX idx_appt_patient ON appointments(patient_id);
CREATE INDEX idx_appt_doctor ON appointments(doctor_id);
CREATE INDEX idx_appt_start ON appointments(start_time);
CREATE INDEX idx_appt_status ON appointments(status);

🔐 Authentication

JWT Token Flow

1. User Login → POST /api/auth/login
2. Server validates credentials
3. Server generates JWT token
4. Client stores token
5. Client includes token in Authorization header
6. Server validates token for protected endpoints

Obtaining a Token

curl -X POST http://localhost:8080/api/auth/login \
 -H "Content-Type: application/json" \
 -d '{
 "username": "admin",
 "password": "admin123"
 }'

{
 "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
 "type": "Bearer",
 "expiresIn": 86400000
}

Using the Token

curl -X GET http://localhost:8080/api/v1/patients \
 -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

🌐 API Endpoints

Base URL

http://localhost:8080/api/v1

Authentication Endpoints

Patient Endpoints

Doctor Endpoints

Appointment Endpoints

📝 API Examples

Create Patient

curl -X POST http://localhost:8080/api/v1/patients \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer YOUR_TOKEN" \
 -d '{
 "firstName": "Rahul",
 "lastName": "Sharma",
 "email": "rahul.sharma@example.com",
 "phone": "+91-9876543210",
 "dob": "1990-05-15",
 "gender": "MALE"
 }'

{
 "id": 1,
 "firstName": "Rahul",
 "lastName": "Sharma",
 "email": "rahul.sharma@example.com",
 "phone": "+91-9876543210",
 "dob": "1990年05月15日",
 "gender": "MALE",
 "createdAt": "2026年01月14日T10:30:00",
 "updatedAt": "2026年01月14日T10:30:00"
}

Create Doctor

curl -X POST http://localhost:8080/api/v1/doctors \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer YOUR_TOKEN" \
 -d '{
 "firstName": "Dr. Priya",
 "lastName": "Patel",
 "email": "priya.patel@hospital.com",
 "specialization": "Cardiology"
 }'

Create Appointment

curl -X POST http://localhost:8080/api/v1/appointments \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer YOUR_TOKEN" \
 -d '{
 "patientId": 1,
 "doctorId": 1,
 "startTime": "2026-01-20T10:00:00",
 "endTime": "2026-01-20T10:30:00",
 "notes": "Regular checkup",
 "status": "SCHEDULED"
 }'

List Patients (with Pagination)

curl -X GET "http://localhost:8080/api/v1/patients?page=0&size=10&sort=lastName,asc" \
 -H "Authorization: Bearer YOUR_TOKEN"

{
 "content": [...],
 "totalElements": 50,
 "totalPages": 5,
 "size": 10,
 "number": 0
}

Search Patients

curl -X GET "http://localhost:8080/api/v1/patients/search?q=sharma" \
 -H "Authorization: Bearer YOUR_TOKEN"

🧪 Testing

Run All Tests

mvn test

Run Specific Test Class

mvn test -Dtest=PatientServiceTest

Run Integration Tests

mvn verify

Test Coverage

mvn clean test jacoco:report

Test Structure

src/test/java/
├── unit/
│ ├── service/
│ │ ├── PatientServiceTest.java
│ │ ├── DoctorServiceTest.java
│ │ └── AppointmentServiceTest.java
│ └── mapper/
│ └── PatientMapperTest.java
└── integration/
 ├── controller/
 │ ├── PatientControllerTest.java
 │ ├── DoctorControllerTest.java
 │ └── AppointmentControllerTest.java
 └── repository/
 └── PatientRepositoryTest.java

Example Unit Test

@ExtendWith(MockitoExtension.class)
class PatientServiceTest {
 
 @Mock
 private PatientRepository patientRepository;
 
 @InjectMocks
 private PatientService patientService;
 
 @Test
 void shouldCreatePatient() {
 // given
 PatientDTO patientDTO = new PatientDTO();
 patientDTO.setFirstName("John");
 
 // when
 PatientDTO result = patientService.createPatient(patientDTO);
 
 // then
 assertNotNull(result);
 assertEquals("John", result.getFirstName());
 }
}

🐳 Docker Deployment

Dockerfile

# Build stage
FROM maven:3.9-eclipse-temurin-17 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline -B
COPY src ./src
RUN mvn clean package -DskipTests
# Runtime stage
FROM eclipse-temurin:17-jre-alpine
WORKDIR /app
COPY --from=build /app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

Docker Compose

version: '3.8'
services:
 postgres:
 image: postgres:15-alpine
 container_name: pms-postgres
 environment:
 POSTGRES_DB: ${POSTGRES_DB:-pms}
 POSTGRES_USER: ${POSTGRES_USER:-pms}
 POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-pms}
 ports:
 - "5432:5432"
 volumes:
 - postgres_data:/var/lib/postgresql/data
 healthcheck:
 test: ["CMD-SHELL", "pg_isready -U pms"]
 interval: 10s
 timeout: 5s
 retries: 5
 api:
 build: .
 container_name: pms-api
 depends_on:
 postgres:
 condition: service_healthy
 environment:
 SPRING_PROFILES_ACTIVE: ${SPRING_PROFILES_ACTIVE:-prod}
 SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/${POSTGRES_DB:-pms}
 SPRING_DATASOURCE_USERNAME: ${POSTGRES_USER:-pms}
 SPRING_DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD:-pms}
 JWT_SECRET: ${JWT_SECRET:-change-me-please}
 ports:
 - "8080:8080"
 restart: unless-stopped
volumes:
 postgres_data:

Build and Run

# Build image
docker build -t patient-management:latest .
# Run with Docker Compose
docker-compose up -d
# View logs
docker-compose logs -f api
# Stop services
docker-compose down
# Clean up volumes
docker-compose down -v

🚀 Production Deployment

Deploy to AWS EC2

Deploy to Heroku

# Login to Heroku
heroku login
# Create app
heroku create patient-management-api
# Add PostgreSQL addon
heroku addons:create heroku-postgresql:mini
# Set environment variables
heroku config:set JWT_SECRET=your-secret-key
# Deploy
git push heroku master
# Open app
heroku open

Deploy to Google Cloud Run

# Build and push to Container Registry
gcloud builds submit --tag gcr.io/PROJECT_ID/patient-management
# Deploy to Cloud Run
gcloud run deploy patient-management \
 --image gcr.io/PROJECT_ID/patient-management \
 --platform managed \
 --region us-central1 \
 --allow-unauthenticated

🔧 Troubleshooting

Common Issues

Issue: Port 8080 already in use

# Find process using port 8080
lsof -i :8080
# Kill the process
kill -9 <PID>
# Or change port in application.yml
server.port=8081

Issue: Database connection refused

# Check PostgreSQL is running
sudo systemctl status postgresql
# Verify credentials in application.yml
# Check if database exists
psql -U pms -d pms -h localhost

Issue: Flyway migration failed

# Check migration files in src/main/resources/db/migration
# Ensure files are named correctly: V1__init.sql
# Repair Flyway
mvn flyway:repair
# Or baseline
mvn flyway:baseline

Issue: JWT token invalid

Issue: Docker build fails

# Clean Docker cache
docker system prune -a
# Rebuild without cache
docker-compose build --no-cache

📊 Monitoring & Logging

Spring Boot Actuator

# Health check
curl http://localhost:8080/actuator/health
# Metrics
curl http://localhost:8080/actuator/metrics
# Info
curl http://localhost:8080/actuator/info

Application Logging

logging:
 file:
 name: logs/patient-management.log
 pattern:
 console: "%d{yyyy-MM-dd HH:mm:ss} - %msg%n"
 file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
 level:
 root: INFO
 com.example.pms: DEBUG

🤝 Contributing

Coding Standards

📝 License

🙏 Acknowledgments

👤 Author

📞 Support

⭐ Show Your Support

🔮 Roadmap