Clinical Patient Flow API

A Java 21 Spring Boot REST API for modeling synthetic clinical patient flow through departments and encounters.

This project is built for healthcare backend practice: REST endpoints, DTOs, validation, exception handling, PostgreSQL persistence, JUnit tests, Docker, GitHub Actions, and Azure deployment readiness.

Important: this project uses synthetic data only. Do not use anything derived from actual Penn patients or any real patient population.

Tech Stack

• Java 21
• Spring Boot
• Spring Web
• Spring Data JPA
• PostgreSQL
• DTOs
• Bean Validation
• Global exception handling
• JUnit 5 / Mockito
• Docker / Docker Compose
• GitHub Actions
• Azure Web App deployment workflow

Endpoints

Method	Endpoint	Description
POST	/patients	Create a synthetic patient
GET	/patients	List patients
GET	/patients/{id}	Get a patient by id
POST	/encounters	Create an encounter
GET	/encounters/{id}	Get an encounter by id
PATCH	/encounters/{id}/status	Update encounter status
GET	/departments/{id}/queue	Get active queue for a department

Architecture

Read the architecture document:

docs/ARCHITECTURE.md

Run Locally With Docker

docker compose up --build

The API will run at:

http://localhost:8080

Swagger UI:

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

Run Locally Without Docker

Start PostgreSQL with a database named clinical_flow, then set:

export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/clinical_flow
export SPRING_DATASOURCE_USERNAME=clinical_user
export SPRING_DATASOURCE_PASSWORD=clinical_password
mvn spring-boot:run

Example Requests

Prepared HTTP requests are in:

docs/requests.http

Create Patient

POST /patients
Content-Type: application/json

{
  "firstName": "Avery",
  "lastName": "Morgan",
  "age": 31,
  "medicalRecordNumber": "SYN-123456"
}

Create Encounter

POST /encounters
Content-Type: application/json

{
  "patientId": 1,
  "departmentId": 1,
  "chiefComplaint": "Synthetic chest discomfort scenario",
  "status": "WAITING"
}

Update Encounter Status

PATCH /encounters/1/status
Content-Type: application/json

{
  "status": "IN_TREATMENT"
}

Encounter Statuses

• WAITING
• IN_TRIAGE
• IN_TREATMENT
• DISCHARGED
• CANCELLED

The API also accepts common variants like in treatment and IN-TREATMENT.

Synthetic Seed Data

On first run, the app creates fake departments, patients, and encounters. All names, complaints, and medical record numbers are synthetic.

Run Tests

mvn test

GitHub Actions

The CI workflow:

• checks out the repo
• sets up Java 21
• starts PostgreSQL service
• runs mvn test
• builds the jar

Azure Deployment

The workflow includes an optional Azure Web App deploy job.

Required GitHub configuration:

• Repository variable: AZURE_WEBAPP_NAME
• Repository secret: AZURE_WEBAPP_PUBLISH_PROFILE

For production-style persistence, connect the Azure Web App to Azure Database for PostgreSQL and set:

• SPRING_DATASOURCE_URL
• SPRING_DATASOURCE_USERNAME
• SPRING_DATASOURCE_PASSWORD

Next Improvements

• Add Flyway database migrations
• Add controller integration tests with Testcontainers
• Add pagination and filtering
• Add role-based security
• Add Azure Container Apps deployment