# Getting Started

If you just joined this codebase, start with the runtime entry point, then trace the request flow through the web layer into the domain model and repositories. This project is the Spring Boot version of PetClinic: a sample veterinary clinic application for managing owners, pets, visits, and veterinarians. It uses Spring MVC, Thymeleaf, Spring Data JPA, validation, and caching to serve both HTML pages and JSON/XML-style resources.

## What This Project Does

PetClinic lets users browse and manage clinic data: owners, pets, veterinary specialties, and visits. The application supports browser-based workflows for searching, creating, and updating records, plus resource-style endpoints for vets. The default setup is intentionally simple so engineers can focus on Spring Boot application structure rather than infrastructure.

## Recommended Reading Order

1. `README.md` — best first stop for local run instructions, database setup, and the overall app shape.
2. `src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java` — the application bootstrap and entry point.
3. `src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java` — the simplest request mapping; use it to understand the view-based web flow.
4. `src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java` and `src/main/java/org/springframework/samples/petclinic/vet/VetController.java` — the main feature flows for the two most visible screens.
5. `src/main/java/org/springframework/samples/petclinic/model/` and the repository interfaces in `owner/` and `vet/` — the shared domain and persistence model.

## Key Entry Points

- [`PetClinicApplication`](src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java) — starts Spring Boot and imports runtime hints.
- [`WelcomeController`](src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java) — maps `/` to the welcome page.
- [`OwnerController`](src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java) — owner creation, search, edit, and detail flows.
- [`VetController`](src/main/java/org/springframework/samples/petclinic/vet/VetController.java) — vet list rendering and resource endpoint.
- [`OwnerRepository`](src/main/java/org/springframework/samples/petclinic/owner/OwnerRepository.java) — owner persistence and search queries.
- [`VetRepository`](src/main/java/org/springframework/samples/petclinic/vet/VetRepository.java) — vet retrieval with caching.
- [`BaseEntity`](src/main/java/org/springframework/samples/petclinic/model/BaseEntity.java), [`Person`](src/main/java/org/springframework/samples/petclinic/model/Person.java), [`NamedEntity`](src/main/java/org/springframework/samples/petclinic/model/NamedEntity.java) — shared entity base classes.
- [`Owner`](src/main/java/org/springframework/samples/petclinic/owner/Owner.java), [`Vet`](src/main/java/org/springframework/samples/petclinic/vet/Vet.java), [`PetValidator`](src/main/java/org/springframework/samples/petclinic/owner/PetValidator.java) — core domain types and form validation.

## Project Structure

The source code is organized by feature area:

- `src/main/java/org/springframework/samples/petclinic/` — application bootstrap and shared infrastructure.
- `src/main/java/org/springframework/samples/petclinic/system/` — cross-cutting web configuration, welcome page, cache setup, and other system-level concerns.
- `src/main/java/org/springframework/samples/petclinic/owner/` — owner, pet, and visit flows.
- `src/main/java/org/springframework/samples/petclinic/vet/` — veterinarian display and specialty data.
- `src/main/java/org/springframework/samples/petclinic/model/` — base JPA classes used across the domain.
- `src/main/resources/` — application properties, message bundles, static resources, templates, and database-specific assets.
- `src/test/` — integration and web tests.

A useful mental model is: controllers handle HTTP, repositories handle persistence, and model classes carry validation and JPA mapping rules.

## Configuration

Start with these files when you need to understand how the app runs:

- `build.gradle` — dependencies, Java version, Checkstyle, test setup, caching libraries, and database drivers.
- `src/main/resources/application-postgres.properties` — PostgreSQL-specific runtime settings.
- `src/main/resources/messages/messages.properties` and the localized variants (`messages_de.properties`, `messages_es.properties`, etc.) — user-facing text and internationalization.
- `src/main/resources/` database and static assets — view templates, styles, seed data, and resource files used at runtime.
- `docker-compose.yml` — local database containers for MySQL/PostgreSQL development.
- `k8s/petclinic.yml` and `k8s/db.yml` — Kubernetes deployment manifests.
- `gradle/wrapper/gradle-wrapper.properties` — pinned Gradle wrapper version.
- `src/checkstyle/nohttp-checkstyle.xml` and `src/checkstyle/nohttp-checkstyle-suppressions.xml` — code style and no-HTTP checks.

## Common Patterns

- **Thin controllers, rich domain objects**: controllers orchestrate request handling, while entities like `Owner` and `Vet` encapsulate relationships and convenience methods.
- **Spring Data repositories**: repository interfaces declare query methods by convention, such as `findByLastNameStartingWith` in [`OwnerRepository`](src/main/java/org/springframework/samples/petclinic/owner/OwnerRepository.java).
- **Pagination everywhere it matters**: list pages load data in small chunks, usually five items at a time.
- **Bean validation plus custom validation**: JPA entities use annotations such as `@NotBlank`, while form-specific checks live in [`PetValidator`](src/main/java/org/springframework/samples/petclinic/owner/PetValidator.java).
- **Caching for read-heavy data**: vets are cached through [`CacheConfiguration`](src/main/java/org/springframework/samples/petclinic/system/CacheConfiguration.java) and `@Cacheable` repository methods.
- **Internationalization by default**: the app uses message bundles plus [`WebConfiguration`](src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java) to switch locales with `?lang=...`.
- **View names map directly to templates**: controller methods usually return a logical view name like `owners/ownerDetails` or `vets/vetList`.

If you only remember one thing: read `PetClinicApplication`, then `OwnerController`, then `Owner` and `OwnerRepository`. That path gives you the clearest end-to-end view of how a request becomes persisted data and a rendered page.