# spring-petclinic/spring-petclinic-rest architecture

> Architecture diagram of the GitHub repository spring-petclinic/spring-petclinic-rest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spring-petclinic/spring-petclinic-rest
- Repository: https://github.com/spring-petclinic/spring-petclinic-rest

## Overview

##### Project type and purpose
- This is a backend‐only REST API microservice for the Spring PetClinic domain.
- It exposes CRUD endpoints for Owners, Pets, Vets, Specialties, PetTypes, Visits, and Users.
- It has no built‐in UI; an external Angular client or other HTTP clients consume the API.

##### File structure
- Top‐level:
- pom.xml, Maven wrapper, GitHub Actions workflows, Docker compose, Postman/Newman scripts, JMeter plan.
- src/main/java/org/springframework/samples/petclinic: Java sources.
- src/main/resources: Spring Boot properties, multi-profile database scripts, OpenAPI spec, logging, i18n.
- src/test: unit/integration tests, performance (JMeter), API tests (Postman/Newman).
- Under Java sources:
- PetClinicApplication.java (Spring Boot entry point).
- config: Swagger/OpenAPI configuration.
- rest/controller & rest/advice: HTTP controllers + exception handling.
- service: business logic (ClinicService, UserService).
- repository: three implementations layers—JDBC, JPA, Spring Data JPA.
- mapper: DTO ↔ Entity mapping (MapStruct).
- model: domain entities (Owner, Pet, Vet, Visit, etc.).
- security: optional Basic authentication config and role definitions.
- util: cross-cutting concerns (monitoring aspect, entity utilities).

##### README for insights
- Supports multiple databases via Spring profiles (H2, HSQLDB, MySQL, PostgreSQL).
- Exposes Swagger UI and OpenAPI (openapi.yml).
- Uses Google Jib for Docker image builds.
- CI pipelines for Maven build, Docker build, and Newman tests.
- API-first approach: code generation for DTOs and API interfaces during Maven build.

a. Main components
- External Clients: Swagger UI, Postman/Newman, Angular front-end (optional), curl/HTTP clients
- API Gateway Layer: Spring MVC REST Controllers
- Service Layer: ClinicService, UserService
- Data Access Layer:
- Repository interfaces
- Implementations: JDBC, JPA, Spring Data JPA
- Domain Model: Entities and DTOs (MapStruct mappers)
- Persistence: Relational Database(s) (H2/HSQLDB/MySQL/Postgres)
- Infrastructure Components:
- Spring Boot App (PetClinicApplication)
- Swagger/OpenAPI
- Actuator (health endpoint)
- Security Module (BasicAuth filter when enabled)
- CI/CD and Testing: GitHub Actions, Docker/Jib, JMeter, Newman/Postman
b. Relationships and interactions
- Clients send HTTP requests → Controllers → Service Layer → Repository Layer → Database
- Controllers use DTOs; mappers convert between DTOs and Entities
- Service Layer may enforce transactions, business rules
- Repository Layer selects implementation based on active Spring profile
- OpenAPI spec drives code generation → generated DTOs and API interfaces appear in target/generated-sources
- Actuator and Swagger are auto‐configured by Spring Boot
c. Architectural patterns and principles
- Layered architecture: Controller → Service → Repository → Database
- API‐first: OpenAPI specification, code generation
- Dependency Injection via Spring Boot
- Profile-based bean selection for multiple database implementations
- Cross‐cutting aspects: security, logging/monitoring (AOP)
d. Key technologies & frameworks
- Spring Boot, Spring MVC, Spring Data JPA, JDBC, MapStruct, OpenAPI Generator, Google Jib
- Databases: H2, HSQLDB, MySQL, PostgreSQL
- Testing: JUnit, Spring Test, JMeter, Postman/Newman
- CI/CD: GitHub Actions, Docker Compose

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients & Tools
    subgraph "External Clients & Tools"
        direction TB
        SwaggerUI["Swagger UI"]:::external
        Postman["Postman/Newman"]:::external
        AngularClient["Angular Frontend"]:::external
        Curl["curl/HTTP Clients"]:::external
        CodeGen["OpenAPI Generator"]:::external
    end

    %% CI/CD & Infra
    subgraph "CI/CD & Infrastructure"
        direction TB
        GitHubActions["GitHub Actions"]:::infra
        DockerCompose["Docker Compose"]:::infra
        PostmanTests["Postman Tests"]:::infra
        JMeterTests["JMeter Tests"]:::infra
    end

    %% OpenAPI Spec
    OpenAPI["openapi.yml"]:::config

    %% Spring Boot Application
    subgraph "Spring PetClinic Application"
        direction TB
        App["PetClinicApplication"]:::app
        Security["Security Module"]:::security
        Actuator["Actuator Endpoints"]:::app
        subgraph "API Gateway Layer"
            direction TB
            Controllers["REST Controllers"]:::controller
            Advice["ExceptionControllerAdvice"]:::controller
        end
        subgraph "Service Layer"
            direction TB
            ClinicSvc["ClinicService"]:::service
            ClinicImpl["ClinicServiceImpl"]:::service
            UserSvc["UserService"]:::service
            UserImpl["UserServiceImpl"]:::service
        end
        subgraph "Repository Layer"
            direction TB
            RepoIntf["Repository Interfaces"]:::repository
            subgraph "JDBC Impl"
                direction TB
                JDBCRepo["jdbc package"]:::repository
            end
            subgraph "JPA Impl"
                direction TB
                JPARepo["jpa package"]:::repository
            end
            subgraph "Spring Data JPA Impl"
                direction TB
                SDJPARepo["springdatajpa package"]:::repository
            end
        end
        subgraph "Domain & Mapping"
            direction TB
            Entities["Domain Entities"]:::domain
            DTOMapper["MapStruct Mappers"]:::mapper
        end
        Config["SwaggerConfig"]:::config
        Util["Cross-Cutting Utilities"]:::util
    end

    %% Database
    DB["Relational Database"]:::database

    %% Relationships
    SwaggerUI -->|view API docs| App
    Postman -->|invoke API| App
    AngularClient -->|invoke API| App
    Curl -->|invoke API| App

    OpenAPI -->|generates DTOs & Interfaces| DTOMapper
    CodeGen -->|uses openapi.yml| OpenAPI

    App -->|initializes| Controllers
    App -->|initializes| Security
    App -->|initializes| Actuator
    App -->|initializes| Config

    Controllers -->|use| Advice
    Controllers -->|call| ClinicSvc
    Controllers -->|call| UserSvc

    ClinicSvc -->|use| DTOMapper
    UserSvc -->|use| DTOMapper
    ClinicSvc -->|call| RepoIntf
    UserSvc -->|call| RepoIntf

    RepoIntf -->|wired by profile| JDBCRepo
    RepoIntf -->|wired by profile| JPARepo
    RepoIntf -->|wired by profile| SDJPARepo

    JDBCRepo -->|CRUD| DB
    JPARepo -->|CRUD| DB
    SDJPARepo -->|CRUD| DB

    DTOMapper -->|map| Entities
    Entities -->|persist| DB

    Util -->|AOP| Controllers
    Util -->|AOP| ClinicSvc
    Util -->|AOP| UserSvc

    %% CI/CD & Tests connections
    GitHubActions -->|build & test| App
    DockerCompose -->|start DB| DB
    PostmanTests -->|run against| App
    JMeterTests -->|run against| App

    %% Click Events
    click App "https://github.com/spring-petclinic/spring-petclinic-rest/blob/master/src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java"
    click Controllers "https://github.com/spring-petclinic/spring-petclinic-rest/tree/master/src/main/java/org/springframework/samples/petclinic/rest/controller"
    click Advice "https://github.com/spring-petclinic/spring-petclinic-rest/blob/master/src/main/java/org/springframework/samples/petclinic/rest/advice/ExceptionControllerAdvice.java"
    click ClinicSvc "https://github.com/spring-petclinic/spring-petclinic-rest/blob/master/src/main/java/org/springframework/samples/petclinic/service/ClinicService.java"
    click ClinicImpl "https://github.com/spring-petclinic/spring-petclinic-rest/blob/master/src/main/java/org/springframework/samples/petclinic/service/ClinicServiceImpl.java"
    click UserSvc "https://github.com/spring-petclinic/spring-petclinic-rest/blob/master/src/main/java/org/springframework/samples/petclinic/service/UserService.java"
    click UserImpl "https://github.com/spring-petclinic/spring-petclinic-rest/blob/master/src/main/java/org/springframework/samples/petclinic/service/UserServiceImpl.java"
    click RepoIntf "https://github.com/spring-petclinic/spring-petclinic-rest/tree/master/src/main/java/org/springframework/samples/petclinic/repository"
    click JDBCRepo "https://github.com/spring-petclinic/spring-petclinic-rest/tree/master/src/main/java/org/springframework/samples/petclinic/repository/jdbc"
    click JPARepo "https://github.com/spring-petclinic/spring-petclinic-rest/tree/master/src/main/java/org/springframework/samples/petclinic/repository/jpa"
    click SDJPARepo "https://github.com/spring-petclinic/spring-petclinic-rest/tree/master/src/main/java/org/springframework/samples/petclinic/repository/springdatajpa"
    click Entities "https://github.com/spring-petclinic/spring-petclinic-rest/tree/master/src/main/java/org/springframework/samples/petclinic/model"
    click DTOMapper "https://github.com/spring-petclinic/spring-petclinic-rest/tree/master/src/main/java/org/springframework/samples/petclinic/mapper"
    click Config "https://github.com/spring-petclinic/spring-petclinic-rest/blob/master/src/main/java/org/springframework/samples/petclinic/config/SwaggerConfig.java"
    click OpenAPI "https://github.com/spring-petclinic/spring-petclinic-rest/blob/master/src/main/resources/openapi.yml"
    click Security "https://github.com/spring-petclinic/spring-petclinic-rest/tree/master/src/main/java/org/springframework/samples/petclinic/security"
    click Util "https://github.com/spring-petclinic/spring-petclinic-rest/tree/master/src/main/java/org/springframework/samples/petclinic/util"
    click GitHubActions "https://github.com/spring-petclinic/spring-petclinic-rest/tree/master/.github/workflows"
    click DockerCompose "https://github.com/spring-petclinic/spring-petclinic-rest/blob/master/docker-compose.yml"
    click PostmanTests "https://github.com/spring-petclinic/spring-petclinic-rest/tree/master/src/test/postman"
    click JMeterTests "https://github.com/spring-petclinic/spring-petclinic-rest/tree/master/src/test/jmeter"

    %% Styles
    classDef external fill:#ffe4b5,stroke:#333,stroke-width:1px
    classDef infra fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef app fill:#add8e6,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef controller fill:#90ee90,stroke:#333,stroke-width:1px
    classDef service fill:#fffacd,stroke:#333,stroke-width:1px
    classDef repository fill:#ffdead,stroke:#333,stroke-width:1px
    classDef domain fill:#f0f8ff,stroke:#333,stroke-width:1px
    classDef mapper fill:#e6e6fa,stroke:#333,stroke-width:1px
    classDef config fill:#fafad2,stroke:#333,stroke-width:1px
    classDef security fill:#ffe4e1,stroke:#333,stroke-width:1px
    classDef util fill:#e0ffff,stroke:#333,stroke-width:1px
    classDef database fill:#fff8dc,stroke:#333,stroke-width:1px,shape:cylinder
```
