How assaad-assaad/clinic works
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: PatientService.java Patient service · ClinicApplication.java Clinic app · PatientController.java Patient API · NationalRegisterNumberConstraint.java NRN rule
Components 15
Application
Spring Boot bootstrap and runtime entrypoint.
- Clinic app · 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 · External HTTP boundary for patients and appointments.
src/main/java/be/ehb/clinic/controller/PatientController.java - Patient service · Coordinates patient lookup, creation, and appointment scheduling.
src/main/java/be/ehb/clinic/service/PatientService.java - NRN rule · Custom constraint used on patient data.
src/main/java/be/ehb/clinic/model/NationalRegisterNumberConstraint.java - NRN 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 · Persisted patient record and API-facing domain model.
src/main/java/be/ehb/clinic/model/Patient.java - Appointment · Persisted appointment record linked to a patient.
src/main/java/be/ehb/clinic/model/Appointment.java - Patient repo · Database access boundary for patients.
src/main/java/be/ehb/clinic/repository/PatientRepository.java - Appointment repo · Database access boundary for appointments.
src/main/java/be/ehb/clinic/repository/AppointmentRepository.java
Infrastructure
Build, runtime configuration, deployment, and CI.
- App config · Environment and database configuration for Spring Boot.
src/main/resources/application.properties - Maven build · Defines dependencies, packaging, and build lifecycle.
pom.xml - Docker image · Containerizes the application for deployment.
Dockerfile - CI workflow · Runs Maven build and tests on changes.
.github/workflows/maven.yml - App tests · Verifies the application context starts successfully.
src/test/java/be/ehb/clinic/ClinicApplicationTests.java - NRN tests · Covers the custom national register number rule.
src/test/java/be/ehb/clinic/model/NationalRegisterNumberValidatorTest.java
Connections 17
- 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.