# Org / Springframework / Samples / Petclinic ## Overview `org.springframework.samples.petclinic` is the root package for the Petclinic sample application. It appears to provide the application bootstrap, runtime hints for native execution, and top-level integration tests that prove the app starts and connects correctly to supported databases. Although most business behavior lives in child packages such as `model`, `owner`, `service`, `system`, and `vet`, this parent package is important because it binds those areas into a runnable Spring Boot application. It is the entry point for startup, native-image support, and broad integration coverage. ## Sub-module Guide ### `model` The `model` package supplies shared domain building blocks such as `BaseEntity`, `NamedEntity`, and `Person`. These types establish the persistence and validation conventions used by the rest of Petclinic. In the bigger picture, `model` is the foundation that both the owner and vet domains build upon. ### `owner` The `owner` package implements the customer-facing clinic workflow around owners, pets, pet types, and visits. It is the main transactional domain slice of the application. Controllers, repositories, validators, and entity relationships work together here to support create, update, and lookup flows. ### `service` The `service` package contains repository-focused integration tests. It exercises the persistence layer end to end, validating the owner graph, pet visits, vet lookup, and reference data. This package acts as the safety net that ensures the model and repository mappings behave as expected when persisted. ### `system` The `system` package holds application-wide web and infrastructure concerns such as the welcome page, the crash endpoint, locale switching, and cache configuration. These pieces are not domain-specific, but they shape how the application behaves as a web system and how supporting features are wired. ### `vet` The `vet` package models veterinarians and specialties and exposes them through read-only controller endpoints. It complements the owner side of the application by representing the clinic staff that can be listed and serialized for browser or API-style access. ### How the sub-modules relate The child packages work together as a layered application: - `model` defines shared persistence primitives. - `owner` and `vet` build business-facing domain slices on top of those primitives. - `system` provides the application shell and cross-cutting behavior. - `service` verifies that the domain and persistence layers cooperate correctly. This appears to be a conventional Spring Boot sample split by concern rather than by technical layer alone. The result is a small codebase where domain modeling, web endpoints, and integration tests each have a distinct home, but still cooperate through shared base types and repositories. ## Key Patterns and Architecture ### Layered but domain-centered design The package structure suggests that Petclinic favors domain-oriented modules with thin controllers and rich entities. The `owner` and `vet` packages both combine entities, repositories, controllers, and supporting infrastructure around a single business area, while `model` provides common inheritance and validation behavior. ### Aggregate-based persistence The owner side appears to treat `Owner` as the aggregate root. Pets and visits are manipulated through the owner graph rather than as isolated records. On the vet side, `Vet` and `Specialty` form a simpler read-mostly model with a cached repository. ### Shared model inheritance The `model` package establishes the inheritance strategy used across the app. `Person` and `NamedEntity` are especially important because they let different modules share identity and naming conventions without repeating mapping code. ### Infrastructure at the edges The `system` package handles application-level concerns that would otherwise clutter the domain modules: homepage routing, intentional failure for error-page demos, locale resolution, and cache bootstrapping. This keeps business packages focused on their own workflows. ### Verification through integration tests The `service` package shows that the application relies on repository-centric integration tests to validate the persistence model. Rather than testing only object behavior, it verifies the actual JPA wiring, seeded data, and cascading saves that the runtime depends on. ```mermaid flowchart LR App["Petclinic application"] --> Model["model"] App --> Owner["owner"] App --> Service["service tests"] App --> System["system"] App --> Vet["vet"] Owner --> Model Service --> Owner Service --> Vet System --> Vet Vet --> Model ``` This diagram shows the overall shape of the package. `model` feeds the domain slices, `owner` and `vet` provide the main business functionality, `system` supports the application shell, and `service` validates that the persistence relationships hold together. ## Dependencies and Integration ### Internal package dependencies From the evidence, this parent package depends directly on: - `org.springframework.samples.petclinic.model` - `org.springframework.samples.petclinic.vet` That fits the observed structure: the root package contains application-level bootstrap code, while the domain and support behavior live in child packages. The vet and model packages are especially important because they provide the shared domain types and repository-backed lookups used elsewhere. ### Spring Boot application entry points The top-level classes include: - [`PetClinicApplication`](src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java:28) — the main Spring Boot application class. - [`PetClinicRuntimeHints`](src/main/java/org/springframework/samples/petclinic/PetClinicRuntimeHints.java:25) — runtime hints support for native or ahead-of-time execution. These classes suggest that the parent package is responsible for starting the app and making it compatible with modern Spring runtime requirements. ### Integration tests The parent package also includes broad integration tests: - [`PetClinicIntegrationTests`](src/test/java/org/springframework/samples/petclinic/PetClinicIntegrationTests.java:34) - [`MySqlIntegrationTests`](src/test/java/org/springframework/samples/petclinic/MySqlIntegrationTests.java:41) - [`PostgresIntegrationTests`](src/test/java/org/springframework/samples/petclinic/PostgresIntegrationTests.java:51) - [`MysqlTestApplication`](src/test/java/org/springframework/samples/petclinic/MysqlTestApplication.java:32) - [`PropertiesLogger`](src/test/java/org/springframework/samples/petclinic/PostgresIntegrationTests.java:94) These tests indicate that the root package is also the place where application startup and database compatibility are validated across environments. This appears to make the parent module the natural location for smoke tests that exercise the entire application stack. ## Notes for Developers - Treat this package as the application boundary. The root classes should stay small and focused on startup or runtime wiring. - `model` is the shared foundation for domain entities, so changes there can ripple into both owner and vet behavior. - The `service` integration tests are valuable regression guards for JPA mappings and seed data. If you change relationships or fixture data, expect to update these tests. - `system` contains infrastructure-style behavior that is user-visible at the application level. Changes there can affect navigation, locale handling, cache behavior, and error pages. - The `vet` package is read-heavy and cache-aware, while the `owner` package is mutation-heavy and workflow-oriented. Keeping that distinction clear will help preserve the current design. - The presence of MySQL and Postgres integration tests suggests the project cares about database portability. Changes to mappings or SQL assumptions should be checked against both databases when possible. - `PetClinicRuntimeHints` implies support for native execution or reflection-sensitive code paths. If you add framework features that rely on reflection or resource loading, this is the place to register them. ## Package Summary Overall, `org.springframework.samples.petclinic` is the orchestration layer for the sample application. It starts Petclinic, supplies runtime hints, and hosts end-to-end tests, while the child packages provide the actual model, workflow, and infrastructure behavior. The modules are intentionally separated so the application can stay easy to understand, but they are designed to operate together as one cohesive clinic system.