# Org / Springframework / Samples / Petclinic ## Overview `org.springframework.samples.petclinic` is the top-level application area for the Petclinic sample. It brings together the shared domain model, the owner and vet feature slices, the system-level web configuration, and the integration tests that exercise the application against a real persistence layer. This appears to be a complete vertical slice of a classic clinic-management application: owners register pets, pets receive visits, vets are listed with specialties, and the system package ties the web experience together with home-page routing, locale selection, caching, and error-handling behavior. The package itself is small at the source level, but it acts as the entry point and coordination point for the rest of the Petclinic module structure. ## Sub-module Guide ### `model` The `model` package provides the shared persistence base classes used throughout Petclinic. `BaseEntity`, `NamedEntity`, and `Person` establish the inheritance pattern that other domain objects rely on for ids, display names, and person-like fields. This package underpins both the owner and vet slices. For example, `Vet` extends `Person`, and `Specialty` extends `NamedEntity`, while owner-side entities use the same base building blocks to keep identity and validation consistent. In other words, `model` is the common language for the rest of the domain. ### `owner` The `owner` package implements the owner-facing workflow. It manages the core aggregate rooted at `Owner`, with `Pet` and `Visit` nested underneath it, and uses `PetType` as lookup data for pet classification. This is the main write-oriented business slice in Petclinic. Controllers handle search, create, edit, and detail flows, while repositories and helper classes keep the aggregate consistent. The package depends on `model` for shared entity behavior and also connects indirectly to the vet world through the broader application, since both slices live in the same persistence and web environment. ### `vet` The `vet` package models veterinarians and their specialties and exposes them for both HTML rendering and serialized responses. `VetRepository` provides read access, `VetController` shapes the response for the UI and resource endpoints, and `Vets` wraps collections for predictable marshalling. This package is read-focused rather than write-focused. It depends on `model` for `Person` and `NamedEntity`, and it uses caching from the system layer to make repeated vet lookups efficient. The vet slice therefore complements the owner slice: one manages clinic customer data, while the other presents clinic staff data. ### `system` The `system` package contains application-wide MVC and infrastructure behavior. It wires the root welcome page, a deliberate crash endpoint used to demonstrate error handling, locale switching, and JCache setup for the `vets` cache. This package is the glue for the rest of the application. It does not own business data, but it defines the shared runtime behavior that owner and vet screens rely on: a stable default locale, a cache manager configuration, and conventional bootstrapping for the home page and failure path. ### `service` The `service` package in this codebase is test support, not a runtime application service layer. It contains integration tests that exercise repository operations, entity relationships, and cascade behavior across the owner and vet domains, plus a small `EntityUtils` helper for locating entities by id in loaded collections. These tests are important because they prove the slices fit together correctly in a real JPA environment. They verify that the owner aggregate persists pets and visits as expected, that vets and specialties load correctly, and that repository methods return the data the web layer depends on. ## Key Patterns and Architecture ### Shared domain foundation The module uses a layered inheritance model to reduce duplication: - `BaseEntity` supplies ids and new-entity detection. - `NamedEntity` adds a validated `name` field. - `Person` adds validated `firstName` and `lastName` fields. That foundation is then reused by both the owner and vet slices, which keeps validation and persistence semantics aligned across the application. ### Aggregate-centric write model The owner slice is organized around the `Owner` aggregate root. Pet and visit changes are applied through the owner rather than by updating child entities in isolation. This keeps relationship handling consistent and makes the controller flow easier to reason about. The service integration tests reinforce this model by saving the owner after mutating pets or visits and then reloading the aggregate to verify the result. ### Read-oriented vet listing with caching The vet slice demonstrates a simpler, read-heavy pattern. Vets are loaded through a repository, sorted and wrapped for serialization, and cached under the `vets` cache name. This works well for a sample application because vet data changes infrequently while being read often by the UI. The cache configuration in `system` supports that usage directly. ### Web infrastructure as shared runtime behavior The system slice sets up application-wide MVC behavior rather than per-feature logic. Locale resolution, locale switching, and the root welcome page are all cross-cutting concerns that affect the whole site. That separation keeps the feature packages focused: owner and vet handle domain workflows, while system handles the global request/response environment those workflows run inside. ### Verification through real integration tests The `service` package shows that Petclinic relies on database-backed integration tests to validate the object graph. Instead of mocking repositories, the tests load actual entities and verify persistence behavior end to end. This is especially important in a sample app whose value comes from demonstrating framework integration patterns rather than just isolated domain methods. ## Dependencies and Integration ### Internal dependencies The top-level module depends most directly on the shared model and vet packages, and the documented child modules show the following relationships: - `org.springframework.samples.petclinic.model` is the base layer for entity inheritance. - `org.springframework.samples.petclinic.owner` depends on the model layer and shapes the owner/pet/visit workflow. - `org.springframework.samples.petclinic.vet` depends on the model layer and exposes veterinarian data. - `org.springframework.samples.petclinic.system` integrates application-wide MVC, caching, and localization behavior. - `org.springframework.samples.petclinic.service` depends on owner, vet, and model types to verify persistence behavior. ### External framework dependencies Across the sub-modules, the codebase uses: - Spring Boot for application startup and runtime wiring - Spring MVC for controllers, routing, and request handling - Spring Data JPA for repositories and persistence integration - Spring Cache and JCache for veterinarian caching - Spring Validation and Jakarta Bean Validation for input and model constraints - Jakarta Persistence for entity mapping - JAXB and serialization support for response wrapping and object marshalling - JUnit, AssertJ, and Spring test support for integration verification ### Application entry points in this package The evidence in this module includes a `PetClinicApplication` bootstrap class and runtime-hints support, plus integration tests for PostgreSQL and MySQL environments. That suggests this package is the executable root of the sample, not merely a library namespace. The main application class starts the Spring Boot context, while runtime hints appear to support ahead-of-time or native-image style execution. The database-specific tests indicate the application is expected to run against different relational backends with the same domain model and repository behavior. ## Mermaid Diagram ```mermaid flowchart TD Petclinic["org.springframework.samples.petclinic"] --> Model["model"] Petclinic --> Owner["owner"] Petclinic --> Vet["vet"] Petclinic --> Service["service"] Petclinic --> System["system"] Owner --> Model Vet --> Model Service --> Owner Service --> Vet System --> Vet ``` ## Notes for Developers - Treat `model` as the shared foundation. If you change base fields or validation there, expect effects in both owner and vet features. - Treat `owner` as the main mutation boundary. Pets and visits are meant to be managed through the owner aggregate, not as isolated records. - Treat `vet` as a read-heavy slice. It is optimized for listing and serialization, and the cache configuration exists to support that usage. - Treat `system` as the application’s cross-cutting layer. Locale, cache, and root-route behavior belong there, not in the individual feature packages. - Treat `service` as an integration safety net. The tests document how repositories, entity mappings, and cascade behavior are expected to work together. - The top-level package includes database-specific integration tests, which implies environment setup matters. If repository behavior changes, verify it against the supported database profiles as well as the default test flow. - This package appears to be structured as a sample application rather than a narrowly scoped library. Preserve that balance between demonstration value and coherent feature boundaries when making changes.