# Getting Started

## What This Project Does
Spring PetClinic is a Spring Boot web application for managing a veterinary clinic. It demonstrates a classic layered Spring MVC application with Thymeleaf views, Spring Data repositories, validation, caching, and multi-database support.

If you are new to the codebase, start by understanding the main web flows, then trace how controllers call repositories, and finally review the configuration that switches the app between H2, MySQL, and PostgreSQL.

## Recommended Reading Order
1. **[`README.md`](README.md)** — best first stop for how to run the app locally, which database profiles exist, and how the project is meant to be used.
2. **[`src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java`](src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java)** — the application entry point and the place to confirm the base package for component scanning.
3. **[`src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java`](src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java)** plus the owner and vet controllers — these show the primary user journeys and how data flows through the app.
4. **[`src/main/resources/application.properties`](src/main/resources/application.properties)** and the profile-specific database files — these explain the runtime environment and persistence setup.
5. **[`k8s/petclinic.yml`](k8s/petclinic.yml)** and **[`docker-compose.yml`](docker-compose.yml)** — use these once you understand the app and want to see how it is deployed or run with external services.

## Key Entry Points
These are the first classes worth reading in source:

- **[`PetClinicApplication`](src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java)** — boots the application with Spring Boot and imports native-image runtime hints.
- **[`WelcomeController`](src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java)** — handles the home page route (`/`) and is the simplest controller to follow end to end.
- **[`OwnerController`](src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java)** — the most instructive CRUD controller; it shows form handling, validation, pagination, redirects, and repository usage.
- **[`VetController`](src/main/java/org/springframework/samples/petclinic/vet/VetController.java)** — demonstrates both HTML view rendering and a JSON-style resource endpoint.
- **[`CacheConfiguration`](src/main/java/org/springframework/samples/petclinic/system/CacheConfiguration.java)** — shows the cache setup used for vet data.
- **[`WebConfiguration`](src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java)** — shows how i18n is wired, including the `lang` URL parameter.

## Project Structure
The codebase is intentionally small and organized by feature area:

- **`org.springframework.samples.petclinic.system`** — application-wide concerns such as welcome page handling, caching, and web configuration.
- **`org.springframework.samples.petclinic.owner`** — owner, pet, and visit flows, including the main CRUD screens.
- **`org.springframework.samples.petclinic.vet`** — vet listings and related domain objects.
- **`org.springframework.samples.petclinic.model`** — shared base entities and common domain helpers.
- **`src/main/resources/templates`** — Thymeleaf templates for the UI.
- **`src/main/resources/messages`** — localized message bundles.
- **`src/main/resources/db`** — database initialization scripts and vendor-specific setup.
- **`src/main/resources/static`** — static assets such as generated CSS and supporting files.

The project currently has only one Java module, so package boundaries are the main way behavior is separated.

## Configuration
The most important config files are:

- **[`src/main/resources/application.properties`](src/main/resources/application.properties)** — the default application configuration.
- **[`src/main/resources/application-postgres.properties`](src/main/resources/application-postgres.properties)** — PostgreSQL profile settings, including the datasource URL, username, and password.
- **[`src/main/resources/application-mysql.properties`](src/main/resources/application-mysql.properties)** — the MySQL equivalent.
- **[`docker-compose.yml`](docker-compose.yml)** — starts local MySQL and PostgreSQL containers for development.
- **[`k8s/db.yml`](k8s/db.yml)** — defines a PostgreSQL demo database and service binding used by Kubernetes.
- **[`k8s/petclinic.yml`](k8s/petclinic.yml)** — deploys the PetClinic app, wires the database binding, and exposes liveness/readiness probes.
- **[`src/main/resources/messages/messages*.properties`](src/main/resources/messages)** — translated UI text for the supported locales.
- **[`src/checkstyle/nohttp-checkstyle.xml`](src/checkstyle/nohttp-checkstyle.xml)** and **[`src/checkstyle/nohttp-checkstyle-suppressions.xml`](src/checkstyle/nohttp-checkstyle-suppressions.xml)** — style rules that keep the codebase consistent.

A few runtime notes:

- The default database is H2 for local development.
- Use the `mysql` or `postgres` Spring profile when connecting to those databases.
- The PostgreSQL profile reads connection details from `POSTGRES_URL`, `POSTGRES_USER`, and `POSTGRES_PASS` if they are set.
- Kubernetes deployment activates the `postgres` profile and expects a service binding at `/bindings`.

## Common Patterns
Read the code with these recurring patterns in mind:

- **Feature-by-package organization** — controllers, repositories, and domain classes live together by feature area.
- **Spring MVC + Thymeleaf** — controllers return view names, populate a `Model`, and use form-backed objects for create/update flows.
- **Validation on form submission** — controller methods commonly combine `@Valid` with `BindingResult` and redirect attributes.
- **Pagination for list screens** — owner and vet listings use `PageRequest` and add paging metadata to the model.
- **Repository-driven persistence** — controllers call repository interfaces directly rather than using a separate service layer.
- **Internationalization** — UI strings come from message bundles and can be switched with `?lang=...`.
- **Caching for reference data** — vet data is cached through JCache configuration.
- **Small, explicit controllers** — the app prefers straightforward request handlers over heavy abstraction.

## What to Read Next
After you finish the files above, move into the feature packages in this order:

1. **`owner` package** — best place to learn the main CRUD and validation patterns.
2. **`vet` package** — best for understanding list rendering, pagination, and JSON responses.
3. **`system` package** — useful once you want to understand the app-wide behaviors such as caching and locale switching.
4. **`model` package** — read last unless you need the shared base types early.

If you are about to make changes, trace one request end to end from controller to repository to template before editing anything. That usually gives the fastest mental model of this codebase.