# Getting Started

This guide is for engineers who just joined the PetClinic codebase and need a fast path into the parts that matter most.

## What This Project Does

PetClinic is a Spring Boot web application for managing veterinary clinic data: owners, pets, visits, veterinarians, and specialties. It uses Spring MVC for the UI, Spring Data for persistence, and JPA entities for the domain model.

The app is intentionally small, but it shows a complete CRUD-style flow end to end, including validation, pagination, localization, and caching.

## Recommended Reading Order

1. **Project entry point and app wiring**
   - [PetClinicApplication](../../src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java)
   - [WebConfiguration](../../src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java)
   - [CacheConfiguration](../../src/main/java/org/springframework/samples/petclinic/system/CacheConfiguration.java)

2. **Core domain model**
   - [BaseEntity](../../src/main/java/org/springframework/samples/petclinic/model/BaseEntity.java)
   - [NamedEntity](../../src/main/java/org/springframework/samples/petclinic/model/NamedEntity.java)
   - [Person](../../src/main/java/org/springframework/samples/petclinic/model/Person.java)
   - [Owner](../../src/main/java/org/springframework/samples/petclinic/owner/Owner.java)
   - [Pet](../../src/main/java/org/springframework/samples/petclinic/owner/Pet.java)
   - [Visit](../../src/main/java/org/springframework/samples/petclinic/owner/Visit.java)
   - [Vet](../../src/main/java/org/springframework/samples/petclinic/vet/Vet.java)
   - [Specialty](../../src/main/java/org/springframework/samples/petclinic/vet/Specialty.java)

3. **Web flow and request handling**
   - [WelcomeController](../../src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java)
   - [OwnerController](../../src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java)
   - [PetController](../../src/main/java/org/springframework/samples/petclinic/owner/PetController.java)
   - [VisitController](../../src/main/java/org/springframework/samples/petclinic/owner/VisitController.java)
   - [VetController](../../src/main/java/org/springframework/samples/petclinic/vet/VetController.java)

4. **Repositories and templates**
   - Read the repository interfaces under `src/main/java/org/springframework/samples/petclinic/**` next, then the views under `src/main/resources/templates/`.

## Key Entry Points

The most important classes to understand first are:

- [PetClinicApplication](../../src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java) — application startup.
- [WelcomeController](../../src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java) — the root route (`/`) and landing page.
- [OwnerController](../../src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java) — owner search, create, edit, and detail views.
- [PetController](../../src/main/java/org/springframework/samples/petclinic/owner/PetController.java) — pet create and edit flows nested under owners.
- [VisitController](../../src/main/java/org/springframework/samples/petclinic/owner/VisitController.java) — visit booking nested under a pet.
- [VetController](../../src/main/java/org/springframework/samples/petclinic/vet/VetController.java) — vet listing for HTML and JSON/XML style responses.
- [Owner](../../src/main/java/org/springframework/samples/petclinic/owner/Owner.java), [Pet](../../src/main/java/org/springframework/samples/petclinic/owner/Pet.java), [Visit](../../src/main/java/org/springframework/samples/petclinic/owner/Visit.java), [Vet](../../src/main/java/org/springframework/samples/petclinic/vet/Vet.java) — the main domain objects.

## Project Structure

The Java code is organized by feature area:

- `model/` contains shared base entities such as `BaseEntity`, `NamedEntity`, and `Person`.
- `owner/` contains owner, pet, and visit domain objects plus the controllers and repositories that manage them.
- `vet/` contains veterinarian and specialty domain objects plus the vet listing controller.
- `system/` contains application-level infrastructure like welcome routing, caching, and web configuration.

A useful mental model is: **domain objects hold state and validation, controllers orchestrate web requests, repositories load and save data, and configuration classes wire cross-cutting concerns**.

## Configuration

These files are the first ones to inspect when you need to understand runtime behavior:

- [src/main/resources/application-postgres.properties](../../src/main/resources/application-postgres.properties) — PostgreSQL-specific application settings.
- [docker-compose.yml](../../docker-compose.yml) — local service orchestration, typically for the app and its database.
- [k8s/db.yml](../../k8s/db.yml) and [k8s/petclinic.yml](../../k8s/petclinic.yml) — Kubernetes deployment manifests.
- [gradle/wrapper/gradle-wrapper.properties](../../gradle/wrapper/gradle-wrapper.properties) — Gradle wrapper version used by the project.
- [src/main/resources/messages/messages.properties](../../src/main/resources/messages/messages.properties) and the localized variants (`messages_de.properties`, `messages_en.properties`, `messages_es.properties`, `messages_fa.properties`, `messages_ko.properties`, `messages_pt.properties`, `messages_ru.properties`) — user-facing text and translations.
- [src/checkstyle/nohttp-checkstyle.xml](../../src/checkstyle/nohttp-checkstyle.xml) and [src/checkstyle/nohttp-checkstyle-suppressions.xml](../../src/checkstyle/nohttp-checkstyle-suppressions.xml) — static analysis rules and exceptions.

Also note:

- [WebConfiguration](../../src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java) enables locale switching with the `lang` query parameter.
- [CacheConfiguration](../../src/main/java/org/springframework/samples/petclinic/system/CacheConfiguration.java) creates the `vets` cache and enables JCache statistics.

## Common Patterns

- **Layered Spring MVC structure**: controllers are thin and delegate to repositories and domain objects.
- **JPA entities with inheritance**: `BaseEntity` provides `id`, `NamedEntity` adds `name`, and `Person` adds `firstName` / `lastName`.
- **Nested ownership relationships**: owners own pets, pets own visits, and vets have specialties.
- **Validation on domain fields**: annotations like `@NotBlank`, `@Pattern`, and `@DateTimeFormat` are placed on entity fields.
- **Defensive request binding**: controllers commonly disallow binding to `id` fields with `WebDataBinder`.
- **Pagination**: owner and vet list pages fetch results in pages of 5.
- **Redirect-after-post**: create and update handlers save data, add flash messages, then redirect.
- **Localized UI text**: message bundles support multiple languages.
- **Cache-aware list rendering**: vet listings are backed by a JCache cache named `vets`.

## Where to Go Next

After this page, read the owner flow in this order:

1. [OwnerController](../../src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java)
2. [PetController](../../src/main/java/org/springframework/samples/petclinic/owner/PetController.java)
3. [VisitController](../../src/main/java/org/springframework/samples/petclinic/owner/VisitController.java)
4. [Owner](../../src/main/java/org/springframework/samples/petclinic/owner/Owner.java)
5. [Pet](../../src/main/java/org/springframework/samples/petclinic/owner/Pet.java)
6. [Visit](../../src/main/java/org/springframework/samples/petclinic/owner/Visit.java)

That sequence shows the main request flow, how nested entities are loaded, and how validation and persistence happen together.