# Org / Springframework / Samples / Petclinic

## Overview

The `org.springframework.samples.petclinic` package is the top-level application area for the Petclinic sample. It appears to tie together the application bootstrap, runtime hints, and the functional subdomains that make up the clinic experience: shared model types, owner/pet management, veterinarian browsing, system-level web infrastructure, and persistence integration tests.

At a business level, this area represents the full clinic application rather than one isolated feature. The child modules combine to support the main user journeys:

- managing owners and their pets,
- recording veterinary visits,
- browsing veterinarians and specialties,
- loading the application home page and error behavior, and
- verifying repository mappings against a real database.

At a technical level, the parent package is lightweight. The indexed sources are centered on application startup and test scaffolding, while the real behavior lives in the subpackages. This suggests the package acts as a composition point for the rest of the sample rather than a domain area with its own large service layer.

## Sub-module Guide

### `model`

The `model` package supplies the shared base entities used across the application. It defines reusable persistence and validation conventions such as generated ids, required names, and person-name fields.

This package is the foundation for the rest of Petclinic. The owner and vet submodules both depend on it because they need shared `Person`, `NamedEntity`, and `BaseEntity` behavior. In practice, `model` keeps the rest of the domain focused on business-specific fields instead of repeating common JPA and validation setup.

### `owner`

The `owner` package implements the owner-centered workflow: searching for owners, editing owner records, managing pets, and adding visits. It combines controllers, domain objects, formatters, validators, and repositories into one aggregate-oriented module.

This appears to be the busiest business area in the application. It depends on the shared model layer for inheritance and on the vet-related domain indirectly for the pet type and visit data used in the clinic workflow. The package is centered on `Owner` as the aggregate root, with pets and visits coordinated through the owner graph rather than as isolated entities.

### `vet`

The `vet` package supports the veterinarian-facing side of the application. It contains the vet domain model, a repository abstraction for loading vets, and a controller that renders both HTML and structured responses.

This module depends on the shared model layer for `Person` and `NamedEntity`, and it exposes a smaller, read-focused slice of the application than the owner package. It is the package most clearly optimized for browsing and serialization rather than mutation-heavy workflows.

### `system`

The `system` package handles cross-cutting web behavior that is not owned by a business domain. It includes the home-page controller, internationalization configuration, cache setup, and a crash controller used to demonstrate error handling.

This package sits alongside the business modules and supports them indirectly. It establishes the applications web environment, which the owner and vet flows rely on for routing, locale selection, and shared infrastructure. In that sense, `system` is the glue for the user-facing shell of the app.

### `service`

The `service` package is test-focused rather than production-focused. It contains repository integration tests that verify the persistence behavior of owners, pets, visits, pet types, and vets against a configured database.

This package connects the functional domains together from a verification perspective. Its tests cross the owner and vet modules and use the shared model contract to assert that entities can be loaded, saved, and related correctly. It acts as a safety net for the data model and repository mappings that the runtime modules depend on.

### How the sub-modules relate

The parent package coordinates a layered application shape:

1. `system` sets up the web shell and shared request behavior.
2. `owner` and `vet` provide the main clinic business flows.
3. `model` supplies reusable base entities and validation rules.
4. `service` verifies that the repository and mapping layer still behaves as expected.

The relationships are mostly one-way:

- `model` feeds the domain submodules with shared inheritance.
- `owner` and `vet` implement separate user journeys but share the same persistence conventions.
- `system` supports both journeys with infrastructure concerns.
- `service` validates the persistence contracts used by the other modules.

## Key Patterns and Architecture

This package uses a classic Spring sample architecture with a few recurring patterns:

- **Shared mapped superclasses** — common persistence and validation behavior lives in the `model` package so concrete domain objects can inherit it.
- **Aggregate-root persistence** — owner-related changes are generally saved through `OwnerRepository` on the owner aggregate rather than through child repositories.
- **Thin controllers, rich support classes** — controllers focus on request flow, while formatters, validators, and domain objects carry the rules and transformations.
- **Read-focused vet access** — the vet module is optimized for browsing and serialization, with caching applied at the repository layer.
- **Cross-cutting system configuration** — locale switching, caching, and error demonstration are centralized outside the business packages.
- **Integration testing against real persistence** — the `service` package confirms the domain and repository contracts using a real JPA slice rather than mocks.

This appears to be a deliberately small but layered application. The package-level design keeps each submodule narrow, yet the combination forms a complete clinic workflow from homepage to data persistence.

### System interaction overview

```mermaid
flowchart TD
Petclinic["org.springframework.samples.petclinic"] --> Model["model"]
Petclinic --> Owner["owner"]
Petclinic --> Vet["vet"]
Petclinic --> System["system"]
Petclinic --> Service["service"]
Model --> SharedDomain["Shared base entities and validation"]
Owner --> OwnerFlows["Owner, pet, visit web flows"]
Vet --> VetFlows["Vet browsing and serialization"]
System --> WebInfra["Home page, locale, cache, error demo"]
Service --> PersistenceTests["Repository integration tests"]
Owner --> Model
Vet --> Model
Service --> Owner
Service --> Vet
System --> PetclinicRuntime["Application bootstrap and runtime hints"]
```

## Dependencies and Integration

The parent package itself is thin, but it connects the application to several important frameworks and neighboring packages:

- **Spring Boot application startup** via `PetClinicApplication`
- **Spring AOT / runtime hints** via `PetClinicRuntimeHints`
- **Spring MVC** through the owner, vet, and system controllers
- **Spring Data JPA** through repository-backed domain access
- **Jakarta Persistence and Validation** through the shared model and entity classes
- **Caching and JCache** through the system and vet packages
- **Test infrastructure** through the integration test classes under the parent package

The evidence shows direct package dependencies from the parent area into `org.springframework.samples.petclinic.model` and `org.springframework.samples.petclinic.vet`, with the owner package also depending on the model layer and the service tests depending on both owner and vet packages. No deeper cross-module relationships were detected in the index, which suggests the application keeps module coupling straightforward and explicit.

## Notes for Developers

- The parent package is mainly a composition and entry point layer. Most feature work will happen in `owner`, `vet`, `system`, or `model`.
- If you change shared model behavior, expect ripple effects in both the owner and vet areas because both rely on the same base types.
- If you change repository mappings or entity relationships, the `service` integration tests are likely to surface the breakage first.
- The `system` package is where app-wide web behavior belongs. Home-page routing, locale switching, cache startup, and error-demo behavior should stay there unless the application structure changes.
- The `vet` module appears optimized for read and serialization behavior, so changes there should preserve stable output shape as well as persistence correctness.
- The owner workflow is aggregate-oriented. Changes to pets or visits should be checked carefully for owner graph consistency.
- The indexed sources in this parent package are small, so `PetClinicApplication`, `PetClinicRuntimeHints`, and the test classes are likely the best entry points when tracing how the whole sample boots and verifies itself.

## Related Sources

- [`PetClinicApplication.java`](src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java)
- [`PetClinicRuntimeHints.java`](src/main/java/org/springframework/samples/petclinic/PetClinicRuntimeHints.java)
- [`package-info.java`](src/main/java/org/springframework/samples/petclinic/package-info.java)
- [`MySqlIntegrationTests.java`](src/test/java/org/springframework/samples/petclinic/MySqlIntegrationTests.java)
- [`MysqlTestApplication.java`](src/test/java/org/springframework/samples/petclinic/MysqlTestApplication.java)
- [`PetClinicIntegrationTests.java`](src/test/java/org/springframework/samples/petclinic/PetClinicIntegrationTests.java)
- [`PostgresIntegrationTests.java`](src/test/java/org/springframework/samples/petclinic/PostgresIntegrationTests.java)