Appointment Booking System

A backend service for booking medical appointments, built to demonstrate Hexagonal Architecture (Ports & Adapters) in a Spring Boot application.

Why Hexagonal Architecture?

The domain logic (conflict detection, cancellation rules) is completely independent of Spring, JPA, or any framework. This means:

• Business rules can be unit tested without a database or Spring context
• Swapping persistence (e.g., from H2 to PostgreSQL) requires no changes to domain or application logic
• The core logic is explicit and easy to reason about

Architecture

domain/          → Pure business logic (Appointment, Doctor, exceptions)
application/     → Use cases + ports (interfaces)
adapter/         → Framework-specific implementations (REST, JPA)
config/          → Spring wiring (bean definitions)

Business Rules

• Two appointments cannot be booked for the same doctor at the same time
• An appointment can only be cancelled if it's more than 24 hours away

Tech Stack

Java 25, Spring Boot 4, Spring Data JPA, H2 (in-memory), JUnit 5, Mockito

Running the project

./gradlew bootRun

Server starts on http://localhost:8080. H2 console available at http://localhost:8080/h2-console.

API Endpoints

Method	Endpoint	Description
POST	/appointments	Book a new appointment
DELETE	/appointments/{id}	Cancel an appointment
GET	/appointments?doctorId={id}	List appointments for a doctor

Example: Book an appointment

curl -X POST http://localhost:8080/appointments \
  -H "Content-Type: application/json" \
  -d '{"doctorId": "doc1", "time": "2026-07-10T14:00:00"}'

Running tests

./gradlew test

Covers domain rules (conflict detection, cancellation eligibility) and application services with Mockito-based unit tests.