# assaad-assaad/clinic architecture

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

- Interactive diagram: https://gitdiagram.com/assaad-assaad/clinic
- Repository: https://github.com/assaad-assaad/clinic

## Overview

1. **Overall shape**
   - This is a **single-module Spring Boot backend** built with **Maven**.
   - It exposes a **REST API** for managing two domain concepts: **patients** and **appointments**.

2. **Application entrypoint**
   - `ClinicApplication.java` is the Spring Boot bootstrap class.
   - At runtime it wires the application context, starts the embedded web server, and activates component scanning for the `be.ehb.clinic` package tree.

3. **HTTP/API layer**
   - `PatientController.java` is the main web boundary.
   - Based on the README, it serves endpoints for:
     - listing patients
     - fetching a patient by id
     - creating a patient
     - creating an appointment for a patient
     - listing today’s appointments
   - This layer should be treated as the only external-facing interface.

4. **Service layer**
   - `PatientService.java` sits between controller and persistence.
   - It likely contains the use-case logic for patient registration, lookup, and appointment scheduling.
   - This layer is where request-level rules are separated from controller concerns and database access.

5. **Persistence layer**
   - `PatientRepository.java` and `AppointmentRepository.java` are Spring Data JPA repositories.
   - They are the repository boundary to the database, abstracting CRUD and query operations away from the service layer.
   - The architecture suggests the app relies on **JPA-managed entities** and a relational database, documented as **MySQL** in the README.

6. **Domain model**
   - `Patient.java` and `Appointment.java` are the core data entities.
   - These models define the persisted clinic domain and likely represent the shape of stored records as well as API payloads.

7. **Validation**
   - `NationalRegisterNumberConstraint.java` and `NationalRegisterNumberValidator.java` implement a **custom validation rule** for patient data.
   - This is a notable domain rule: patient registration is not just basic CRUD, it includes validation of a national register number.
   - Spring validation (`@Valid`) is part of the request-to-domain boundary.

8. **Data flow**
   - The typical flow is: **HTTP request → controller → service → repository → database**, then back through the same layers as a response.
   - Appointment creation is likely dependent on patient existence, so patient identity is the key linkage between the two domain objects.

9. **Configuration**
   - `src/main/resources/application.properties` holds runtime configuration, likely including server and database settings.
   - This file is the main environment-specific boundary for connecting the app to MySQL and tuning Spring Boot behavior.

10. **Build, packaging, and deployment**
   - `pom.xml` defines the Java/Spring dependencies and build lifecycle.
   - `Dockerfile` indicates the app can be containerized for deployment.
   - The Maven wrapper files support reproducible builds without requiring a preinstalled Maven version.

11. **Testing**
   - `ClinicApplicationTests.java` provides application-level smoke testing.
   - `NationalRegisterNumberValidatorTest.java` focuses on the custom validation rule, which is one of the most important business-specific constraints in the repo.
   - The tests show that validation logic is treated as a first-class concern, not just persistence.

12. **CI/CD**
   - `.github/workflows/maven.yml` suggests GitHub Actions runs the Maven build/test pipeline automatically.
   - This forms the repository’s delivery gate, ensuring the Spring Boot app and its tests pass before changes are accepted.

13. **Architecture boundaries to diagram**
   - A clean diagram for this repo should show four main zones:
     - **Client/API layer**: REST endpoints in the controller
     - **Business layer**: service logic and validation
     - **Persistence layer**: Spring Data repositories
     - **Infrastructure**: MySQL, application properties, Docker, and CI
   - The most important cross-cutting concern is **validation**, especially the custom national register number rule.

Main entry points: [`src/main/java/be/ehb/clinic/service/PatientService.java`](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/service/PatientService.java) (Patient service), [`src/main/java/be/ehb/clinic/ClinicApplication.java`](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/ClinicApplication.java) (Clinic app), [`src/main/java/be/ehb/clinic/controller/PatientController.java`](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/controller/PatientController.java) (Patient API), [`src/main/java/be/ehb/clinic/model/NationalRegisterNumberConstraint.java`](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/model/NationalRegisterNumberConstraint.java) (NRN rule)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_clinic_application(("Clinic app<br/>Spring Boot entrypoint"))
end

subgraph group_api["API & Service"]
  node_patient_controller["Patient API<br/>REST controller"]
  node_patient_service["Patient service<br/>use-case service"]
  node_nrn_constraint{{"NRN rule<br/>validation annotation"}}
  node_nrn_validator["NRN validator<br/>constraint validator"]
end

subgraph group_domain["Domain & Persistence"]
  node_patient_entity["Patient<br/>JPA entity<br/>[Patient.java]"]
  node_appointment_entity["Appointment<br/>JPA entity<br/>[Appointment.java]"]
  node_patient_repo[("Patient repo<br/>Spring Data repository")]
  node_appointment_repo[("Appointment repo<br/>Spring Data repository")]
end

subgraph group_infra["Infrastructure"]
  node_app_properties["App config<br/>runtime properties"]
  node_pom["Maven build<br/>build descriptor<br/>[pom.xml]"]
  node_dockerfile["Docker image<br/>container spec"]
  node_github_actions["CI workflow<br/>GitHub Actions<br/>[maven.yml]"]
  node_app_test["App tests<br/>smoke tests"]
  node_nrn_test["NRN tests<br/>validator tests"]
end

node_clinic_application -->|"scans/starts"| node_patient_controller
node_patient_controller -->|"delegates"| node_patient_service
node_patient_controller -->|"validates"| node_nrn_constraint
node_nrn_constraint -->|"implemented by"| node_nrn_validator
node_patient_service -->|"reads/writes"| node_patient_repo
node_patient_service -->|"schedules"| node_appointment_repo
node_patient_service -->|"uses"| node_patient_entity
node_patient_service -->|"uses"| node_appointment_entity
node_patient_repo -->|"persists"| node_patient_entity
node_appointment_repo -->|"persists"| node_appointment_entity
node_patient_entity -->|"annotated with"| node_nrn_constraint
node_app_properties -.->|"configures"| node_clinic_application
node_pom -.->|"builds"| node_clinic_application
node_dockerfile -.->|"packages"| node_clinic_application
node_github_actions -.->|"runs"| node_pom
node_app_test -.->|"verifies"| node_clinic_application
node_nrn_test -.->|"verifies"| node_nrn_validator

click node_clinic_application "https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/ClinicApplication.java"
click node_patient_controller "https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/controller/PatientController.java"
click node_patient_service "https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/service/PatientService.java"
click node_nrn_constraint "https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/model/NationalRegisterNumberConstraint.java"
click node_nrn_validator "https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/model/NationalRegisterNumberValidator.java"
click node_patient_entity "https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/model/Patient.java"
click node_appointment_entity "https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/model/Appointment.java"
click node_patient_repo "https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/repository/PatientRepository.java"
click node_appointment_repo "https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/repository/AppointmentRepository.java"
click node_app_properties "https://github.com/assaad-assaad/clinic/blob/master/src/main/resources/application.properties"
click node_pom "https://github.com/assaad-assaad/clinic/blob/master/pom.xml"
click node_dockerfile "https://github.com/assaad-assaad/clinic/tree/master/Dockerfile"
click node_github_actions "https://github.com/assaad-assaad/clinic/blob/master/.github/workflows/maven.yml"
click node_app_test "https://github.com/assaad-assaad/clinic/blob/master/src/test/java/be/ehb/clinic/ClinicApplicationTests.java"
click node_nrn_test "https://github.com/assaad-assaad/clinic/blob/master/src/test/java/be/ehb/clinic/model/NationalRegisterNumberValidatorTest.java"

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_clinic_application toneBlue
class node_patient_controller,node_patient_service,node_nrn_constraint,node_nrn_validator toneAmber
class node_patient_entity,node_appointment_entity,node_patient_repo,node_appointment_repo toneMint
class node_app_properties,node_pom,node_dockerfile,node_github_actions,node_app_test,node_nrn_test toneRose
```

## Components

### Application

Spring Boot bootstrap and runtime entrypoint.

- [Clinic app](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/ClinicApplication.java): Spring Boot entrypoint · Bootstraps the application context and embedded server. · `src/main/java/be/ehb/clinic/ClinicApplication.java`

### API & Service

REST boundary, use-case orchestration, and validation.

- [Patient API](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/controller/PatientController.java): REST controller · External HTTP boundary for patients and appointments. · `src/main/java/be/ehb/clinic/controller/PatientController.java`
- [Patient service](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/service/PatientService.java): use-case service · Coordinates patient lookup, creation, and appointment scheduling. · `src/main/java/be/ehb/clinic/service/PatientService.java`
- [NRN rule](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/model/NationalRegisterNumberConstraint.java): validation annotation · Custom constraint used on patient data. · `src/main/java/be/ehb/clinic/model/NationalRegisterNumberConstraint.java`
- [NRN validator](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/model/NationalRegisterNumberValidator.java): constraint validator · Implements the national register number validation logic. · `src/main/java/be/ehb/clinic/model/NationalRegisterNumberValidator.java`

### Domain & Persistence

Clinic entities and Spring Data repositories.

- [Patient](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/model/Patient.java): JPA entity · Persisted patient record and API-facing domain model. · `src/main/java/be/ehb/clinic/model/Patient.java`
- [Appointment](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/model/Appointment.java): JPA entity · Persisted appointment record linked to a patient. · `src/main/java/be/ehb/clinic/model/Appointment.java`
- [Patient repo](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/repository/PatientRepository.java): Spring Data repository · Database access boundary for patients. · `src/main/java/be/ehb/clinic/repository/PatientRepository.java`
- [Appointment repo](https://github.com/assaad-assaad/clinic/blob/master/src/main/java/be/ehb/clinic/repository/AppointmentRepository.java): Spring Data repository · Database access boundary for appointments. · `src/main/java/be/ehb/clinic/repository/AppointmentRepository.java`

### Infrastructure

Build, runtime configuration, deployment, and CI.

- [App config](https://github.com/assaad-assaad/clinic/blob/master/src/main/resources/application.properties): runtime properties · Environment and database configuration for Spring Boot. · `src/main/resources/application.properties`
- [Maven build](https://github.com/assaad-assaad/clinic/blob/master/pom.xml): build descriptor · Defines dependencies, packaging, and build lifecycle. · `pom.xml`
- [Docker image](https://github.com/assaad-assaad/clinic/tree/master/Dockerfile): container spec · Containerizes the application for deployment. · `Dockerfile`
- [CI workflow](https://github.com/assaad-assaad/clinic/blob/master/.github/workflows/maven.yml): GitHub Actions · Runs Maven build and tests on changes. · `.github/workflows/maven.yml`
- [App tests](https://github.com/assaad-assaad/clinic/blob/master/src/test/java/be/ehb/clinic/ClinicApplicationTests.java): smoke tests · Verifies the application context starts successfully. · `src/test/java/be/ehb/clinic/ClinicApplicationTests.java`
- [NRN tests](https://github.com/assaad-assaad/clinic/blob/master/src/test/java/be/ehb/clinic/model/NationalRegisterNumberValidatorTest.java): validator tests · Covers the custom national register number rule. · `src/test/java/be/ehb/clinic/model/NationalRegisterNumberValidatorTest.java`

## Connections

- Clinic app → Patient API: scans/starts · Bootstraps the web layer through Spring component scanning.
- Patient API → Patient service: delegates · HTTP requests are translated into clinic use cases.
- Patient API → NRN rule: validates · Request payloads use Bean Validation on patient input.
- NRN rule → NRN validator: implemented by · The custom annotation is backed by a validator class.
- Patient service → Patient repo: reads/writes · Patient use cases persist and fetch patient data.
- Patient service → Appointment repo: schedules · Appointment creation is persisted through the repository layer.
- Patient service → Patient: uses · Service logic operates on patient domain records.
- Patient service → Appointment: uses · Service logic creates and queries appointment records.
- Patient repo → Patient: persists · Repository manages patient entity storage.
- Appointment repo → Appointment: persists · Repository manages appointment entity storage.
- Patient → NRN rule: annotated with · Patient data includes the custom validation rule.
- App config → Clinic app: configures · Runtime properties shape application startup behavior.
- Maven build → Clinic app: builds · Maven packages and compiles the Spring Boot app.
- Docker image → Clinic app: packages · Container image runs the application artifact.
- CI workflow → Maven build: runs · CI executes the Maven build and test lifecycle.
- App tests → Clinic app: verifies · Smoke test checks application startup wiring.
- NRN tests → NRN validator: verifies · Unit test checks the custom validation logic.
