# Getting Started

If you are new to this codebase, start here. Petclinic is a small Spring Boot application for managing a veterinary clinic: owners, pets, visits, veterinarians, and specialty lookup data. It is intentionally simple, which makes it a good place to learn the application flow from web request to persistence.

## What This Project Does

The application provides a classic clinic workflow: search for owners, create and edit owners and pets, add visits, and list veterinarians. It also includes cross-cutting behavior like localization, caching, and health endpoints for deployment environments.

The UI is server-rendered with Spring MVC and Thymeleaf, with persistence handled through Spring Data JPA and JPA entities.

## Recommended Reading Order

1. **Project entry point** — read [`src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java`](src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java) to understand how the app starts.
2. **Shared model layer** — read the classes in `model/` next, especially [`BaseEntity`](src/main/java/org/springframework/samples/petclinic/model/BaseEntity.java), [`NamedEntity`](src/main/java/org/springframework/samples/petclinic/model/NamedEntity.java), and [`Person`](src/main/java/org/springframework/samples/petclinic/model/Person.java).
3. **Core business flow** — move into `owner/` and read [`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), then the controllers.
4. **Read-only vet flow** — read the `vet/` package, especially [`Vet`](src/main/java/org/springframework/samples/petclinic/vet/Vet.java) and [`VetController`](src/main/java/org/springframework/samples/petclinic/vet/VetController.java).
5. **System wiring** — finish with `system/` to see locale changes, caching, and application-wide MVC configuration.
6. **Tests and examples** — use the integration tests under `src/test/java` as executable documentation when you change behavior.

## Key Entry Points

These are the most useful classes to understand first:

- [`PetClinicApplication`](src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java) — the Spring Boot main class.
- [`OwnerController`](src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java) — owner search, create, and update flows.
- [`PetController`](src/main/java/org/springframework/samples/petclinic/owner/PetController.java) — nested pet editing and validation behavior.
- [`VisitController`](src/main/java/org/springframework/samples/petclinic/owner/VisitController.java) — visit creation for an owner’s pet.
- [`OwnerRepository`](src/main/java/org/springframework/samples/petclinic/owner/OwnerRepository.java) and [`PetTypeRepository`](src/main/java/org/springframework/samples/petclinic/owner/PetTypeRepository.java) — persistence access for the owner domain.
- [`VetController`](src/main/java/org/springframework/samples/petclinic/vet/VetController.java) and [`VetRepository`](src/main/java/org/springframework/samples/petclinic/vet/VetRepository.java) — vet listing and cached reads.
- [`WebConfiguration`](src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java) — locale switching and request-level MVC setup.
- [`CacheConfiguration`](src/main/java/org/springframework/samples/petclinic/system/CacheConfiguration.java) — JCache setup for the `vets` cache.

## Project Structure

The source is organized by domain and support layer:

- `src/main/java/org/springframework/samples/petclinic/`
  - `model/` — shared base entities and common validation types
  - `owner/` — owner, pet, visit, and related web/repository classes
  - `vet/` — veterinarian read views and repositories
  - `system/` — app-wide MVC, caching, and home-page wiring
- `src/main/resources/`
  - `application.properties` and profile-specific variants for runtime configuration
  - `messages/` for localized text
  - `static/` and `templates/` for web assets and Thymeleaf views
  - `db/` for schema/data scripts used by the different database profiles
- `src/test/` — tests and integration scenarios that show the intended behavior
- `k8s/` and `docker-compose.yml` — deployment and local database setup examples

## Configuration

A few files are worth knowing immediately:

- [`src/main/resources/application.properties`](src/main/resources/application.properties) — default H2 setup, JPA settings, message bundle configuration, actuator exposure, and static-resource caching.
- [`src/main/resources/application-postgres.properties`](src/main/resources/application-postgres.properties) — PostgreSQL profile configuration and SQL initialization.
- [`docker-compose.yml`](docker-compose.yml) — local MySQL and PostgreSQL containers for development.
- [`k8s/db.yml`](k8s/db.yml) and [`k8s/petclinic.yml`](k8s/petclinic.yml) — Kubernetes manifests for running the app with a database binding.
- [`gradle/wrapper/gradle-wrapper.properties`](gradle/wrapper/gradle-wrapper.properties) — pinned Gradle version used by the wrapper.
- [`src/main/resources/messages/messages.properties`](src/main/resources/messages/messages.properties) and the localized variants — user-facing text and translations.

## Common Patterns

A few conventions show up throughout the codebase:

- **Feature-by-package organization** — classes are grouped by domain area, not by technical layer alone.
- **Controller + repository pairs** — each main flow is easy to trace from web endpoint to persistence.
- **Mapped base entities** — shared JPA and validation behavior lives in `model/` to avoid repetition.
- **Form binding safety** — controllers use binder restrictions and validation to prevent unwanted field binding.
- **Paging for lists** — owner and vet screens use page-based queries rather than loading everything at once.
- **Internationalization-ready views** — user-visible strings come from message bundles instead of being hard-coded.
- **Environment-specific startup** — database behavior changes with profiles such as `h2` and `postgres`.
- **Infrastructure-focused tests** — integration tests double as documentation for the persistence and web contract.

## How to Start Contributing Safely

When you make a change, follow this order:

1. Read the relevant entity first.
2. Trace the controller that uses it.
3. Check the repository method or query that backs it.
4. Update or add tests that show the intended behavior.
5. Verify any config or message bundle changes if the change affects startup or UI text.

If you only remember one thing: start in [`PetClinicApplication`](src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java), then follow the `owner/` package. That path gives you the fastest route to understanding the application end to end.