# clancymendonca/patient-management architecture

> Architecture diagram of the GitHub repository clancymendonca/patient-management, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/clancymendonca/patient-management
- Repository: https://github.com/clancymendonca/patient-management

## Overview

#### Purpose and runtime
This repository implements a standalone patient-management REST service. It is a Java/Spring Boot application built with Maven, with its process entry point at `patient-service/src/main/java/com/pm/patientservice/PatientServiceApplication.java` and build/dependency definition in `patient-service/pom.xml`.

#### HTTP API boundary
`PatientController` exposes the patient-facing HTTP endpoints and is the primary inbound boundary: `patient-service/src/main/java/com/pm/patientservice/controller/PatientController.java`. Example requests for retrieving, creating, and updating patients are supplied under `api-requests/patient-service/get-patients.http`, `api-requests/patient-service/set-patient.http`, and `api-requests/patient-service/update-patient.http`.

#### Request/response contract and validation
The API separates external payloads from persistence entities through DTOs:
- `patient-service/src/main/java/com/pm/patientservice/dto/PatientRequestDTO.java`
- `patient-service/src/main/java/com/pm/patientservice/dto/PatientResponseDTO.java`

Creation-specific validation is modeled with `patient-service/src/main/java/com/pm/patientservice/dto/validators/CreatePatientValidationGroup.java`, allowing validation rules to vary by operation rather than being coupled directly to the database model.

#### Application service flow
`PatientService` owns patient use cases and mediates between controller, mapping, and persistence: `patient-service/src/main/java/com/pm/patientservice/service/PatientService.java`. The expected control path is HTTP request → validated request DTO → service operation → repository access → mapped response DTO. This keeps HTTP handling and database operations out of the central business-operation layer.

#### Mapping and domain persistence
`PatientMapper` translates between API DTOs and the patient domain/persistence entity: `patient-service/src/main/java/com/pm/patientservice/mapper/PatientMapper.java`. Persistent patient state is represented by `patient-service/src/main/java/com/pm/patientservice/model/Patient.java` and accessed through `patient-service/src/main/java/com/pm/patientservice/repository/PatientRepository.java`, indicating a Spring Data/JPA-style database boundary.

#### Error semantics
Domain failures are explicit: missing patients use `patient-service/src/main/java/com/pm/patientservice/exception/PatientNotFoundException.java`, while uniqueness conflicts use `patient-service/src/main/java/com/pm/patientservice/exception/EmailAlreadyExistsException.java`. `patient-service/src/main/java/com/pm/patientservice/exception/GlobalExceptionHandler.java` centralizes translation of these failures into consistent HTTP error responses, preventing exception details from leaking across the API boundary.

#### Configuration and data initialization
Runtime configuration resides in `patient-service/src/main/resources/application.properties`. Initial database content is provisioned through `patient-service/src/main/resources/data.sql`, making database initialization part of the application startup boundary. No external service integrations are evident from the repository structure; the material infrastructure dependency is the configured relational persistence layer.

Main entry points: [`patient-service/src/main/java/com/pm/patientservice/service/PatientService.java`](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/service/PatientService.java) (Patient service), [`patient-service/src/main/java/com/pm/patientservice/controller/PatientController.java`](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/controller/PatientController.java) (Patient controller), [`patient-service/src/main/java/com/pm/patientservice/PatientServiceApplication.java`](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/PatientServiceApplication.java) (Spring Boot application), [`patient-service/src/main/java/com/pm/patientservice/mapper/PatientMapper.java`](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/mapper/PatientMapper.java) (Patient mapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_maven["Maven build<br/>build definition<br/>[pom.xml]"]
  node_application{{"Spring Boot application<br/>process entry point"}}
  node_config["Runtime configuration<br/>application properties"]
end

subgraph group_api["HTTP API"]
  node_controller["Patient controller<br/>REST controller"]
  node_request_dto["Patient request DTO<br/>API input contract"]
  node_validation_group["Create validation group<br/>validation policy"]
  node_response_dto["Patient response DTO<br/>API output contract"]
  node_exception_handler["Global exception handler<br/>HTTP error translator"]
end

subgraph group_application["Application"]
  node_service["Patient service<br/>application service"]
  node_mapper["Patient mapper<br/>DTO/entity mapper<br/>[PatientMapper.java]"]
  node_not_found["Patient not found<br/>domain exception"]
  node_email_exists["Email already exists<br/>domain exception"]
end

subgraph group_persistence["Persistence"]
  node_repository["Patient repository<br/>Spring Data repository"]
  node_patient["Patient<br/>JPA entity<br/>[Patient.java]"]
  node_database[("Relational database<br/>configured persistence store")]
  node_seed_data["Initial patient data<br/>database seed script<br/>[data.sql]"]
end

node_maven -->|"builds"| node_application
node_application -->|"loads"| node_config
node_application -->|"initializes"| node_seed_data
node_controller -->|"accepts"| node_request_dto
node_request_dto -->|"validated for create"| node_validation_group
node_controller -->|"invokes"| node_service
node_service -->|"maps through"| node_mapper
node_mapper -->|"produces"| node_response_dto
node_service -->|"accesses"| node_repository
node_mapper -->|"maps to/from"| node_patient
node_repository -->|"persists"| node_patient
node_repository -->|"reads and writes"| node_database
node_config -.->|"configures"| node_database
node_seed_data -->|"seeds"| node_database
node_service -.->|"raises"| node_not_found
node_service -.->|"raises"| node_email_exists
node_exception_handler -->|"translates"| node_not_found
node_exception_handler -->|"translates"| node_email_exists
node_controller -.->|"routes failures to"| node_exception_handler

click node_maven "https://github.com/clancymendonca/patient-management/blob/master/patient-service/pom.xml"
click node_application "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/PatientServiceApplication.java"
click node_config "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/resources/application.properties"
click node_controller "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/controller/PatientController.java"
click node_request_dto "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/dto/PatientRequestDTO.java"
click node_validation_group "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/dto/validators/CreatePatientValidationGroup.java"
click node_response_dto "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/dto/PatientResponseDTO.java"
click node_exception_handler "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/exception/GlobalExceptionHandler.java"
click node_service "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/service/PatientService.java"
click node_mapper "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/mapper/PatientMapper.java"
click node_not_found "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/exception/PatientNotFoundException.java"
click node_email_exists "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/exception/EmailAlreadyExistsException.java"
click node_repository "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/repository/PatientRepository.java"
click node_patient "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/model/Patient.java"
click node_seed_data "https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/resources/data.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_maven,node_application,node_config toneBlue
class node_controller,node_request_dto,node_validation_group,node_response_dto,node_exception_handler toneAmber
class node_service,node_mapper,node_not_found,node_email_exists toneMint
class node_repository,node_patient,node_database,node_seed_data toneRose
```

## Components

### Runtime

- [Maven build](https://github.com/clancymendonca/patient-management/blob/master/patient-service/pom.xml): build definition · `patient-service/pom.xml`
- [Spring Boot application](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/PatientServiceApplication.java): process entry point · `patient-service/src/main/java/com/pm/patientservice/PatientServiceApplication.java`
- [Runtime configuration](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/resources/application.properties): application properties · `patient-service/src/main/resources/application.properties`

### HTTP API

- [Patient controller](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/controller/PatientController.java): REST controller · Primary inbound HTTP boundary. · `patient-service/src/main/java/com/pm/patientservice/controller/PatientController.java`
- [Patient request DTO](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/dto/PatientRequestDTO.java): API input contract · `patient-service/src/main/java/com/pm/patientservice/dto/PatientRequestDTO.java`
- [Create validation group](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/dto/validators/CreatePatientValidationGroup.java): validation policy · Applies creation-specific request validation. · `patient-service/src/main/java/com/pm/patientservice/dto/validators/CreatePatientValidationGroup.java`
- [Patient response DTO](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/dto/PatientResponseDTO.java): API output contract · `patient-service/src/main/java/com/pm/patientservice/dto/PatientResponseDTO.java`
- [Global exception handler](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/exception/GlobalExceptionHandler.java): HTTP error translator · `patient-service/src/main/java/com/pm/patientservice/exception/GlobalExceptionHandler.java`

### Application

- [Patient service](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/service/PatientService.java): application service · Owns patient use cases. · `patient-service/src/main/java/com/pm/patientservice/service/PatientService.java`
- [Patient mapper](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/mapper/PatientMapper.java): DTO/entity mapper · `patient-service/src/main/java/com/pm/patientservice/mapper/PatientMapper.java`
- [Patient not found](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/exception/PatientNotFoundException.java): domain exception · `patient-service/src/main/java/com/pm/patientservice/exception/PatientNotFoundException.java`
- [Email already exists](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/exception/EmailAlreadyExistsException.java): domain exception · `patient-service/src/main/java/com/pm/patientservice/exception/EmailAlreadyExistsException.java`

### Persistence

- [Patient repository](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/repository/PatientRepository.java): Spring Data repository · `patient-service/src/main/java/com/pm/patientservice/repository/PatientRepository.java`
- [Patient](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/java/com/pm/patientservice/model/Patient.java): JPA entity · Persistent patient state. · `patient-service/src/main/java/com/pm/patientservice/model/Patient.java`
- **Relational database**: configured persistence store
- [Initial patient data](https://github.com/clancymendonca/patient-management/blob/master/patient-service/src/main/resources/data.sql): database seed script · Provisioned during application startup. · `patient-service/src/main/resources/data.sql`

## Connections

- Maven build → Spring Boot application: builds
- Spring Boot application → Runtime configuration: loads
- Spring Boot application → Initial patient data: initializes
- Patient controller → Patient request DTO: accepts
- Patient request DTO → Create validation group: validated for create
- Patient controller → Patient service: invokes
- Patient service → Patient mapper: maps through
- Patient mapper → Patient response DTO: produces
- Patient service → Patient repository: accesses
- Patient mapper → Patient: maps to/from
- Patient repository → Patient: persists
- Patient repository → Relational database: reads and writes
- Runtime configuration → Relational database: configures
- Initial patient data → Relational database: seeds
- Patient service → Patient not found: raises
- Patient service → Email already exists: raises
- Global exception handler → Patient not found: translates
- Global exception handler → Email already exists: translates
- Patient controller → Global exception handler: routes failures to