# Getting Started

## What This Project Does
PetClinic is a Spring Boot sample application for managing veterinary clinic data. It demonstrates a conventional layered Spring MVC application with owners, pets, visits, and veterinarians, plus internationalized UI messages and multiple deployment options.

If you are new to the codebase, focus first on the domain model and the web flow. Most changes will start in the `petclinic` package and then fan out into repositories, controllers, views, and configuration.

## Recommended Reading Order
1. **[Project overview]** - Start with the app entry point and the high-level domain layout.
2. **[Domain model]** - Read the shared model base classes, then the owner/pet/vet entities.
3. **[Web flow]** - Review the main MVC controllers and how they load and validate form data.
4. **[Configuration]** - Finish with runtime configuration, database setup, and deployment manifests.

## Key Entry Points
These classes are the best starting points for understanding the codebase:

- [`PetClinicApplication`](src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java) - application bootstrap and the top-level Spring Boot entry point.
- [`BaseEntity`](src/main/java/org/springframework/samples/petclinic/model/BaseEntity.java) - shared JPA identity behavior used by most domain objects.
- [`NamedEntity`](src/main/java/org/springframework/samples/petclinic/model/NamedEntity.java) - shared naming behavior for entities like pet types and specialties.
- [`OwnerController`](src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java) - the main example of form handling, validation, pagination, and redirects.
- [`VetController`](src/main/java/org/springframework/samples/petclinic/vet/VetController.java) - the main read-only listing controller and JSON/XML-friendly resource endpoint.

## Project Structure
The code is organized under `src/main/java/org/springframework/samples/petclinic` with a small set of feature packages:

- `model` - shared JPA base classes and cross-cutting domain abstractions.
- `owner` - owner, pet, pet type, and visit domain objects plus the main CRUD and search controllers.
- `vet` - veterinarian and specialty domain objects plus the vet listing controller.
- `system` - app-wide web configuration, welcome/crash handling, and cache support.

A few practical cues when navigating the code:

- Controllers are package-scoped and use constructor injection.
- Repositories encapsulate persistence and are called directly from controllers.
- Views are organized by feature area, with controller return values pointing at templates such as `owners/*` and `vets/*`.
- Validation and data binding are handled close to the controller method that owns the request.

## Configuration
These files matter most when you are trying to run, deploy, or customize the app:

- [`docker-compose.yml`](docker-compose.yml) - local MySQL and Postgres containers for development.
- [`src/main/resources/application-postgres.properties`](src/main/resources/application-postgres.properties) - Postgres profile settings and datasource defaults.
- [`k8s/petclinic.yml`](k8s/petclinic.yml) - Kubernetes deployment for the app, including health probes and service binding mounts.
- [`k8s/db.yml`](k8s/db.yml) - Kubernetes database deployment and secret wiring for the demo Postgres instance.
- [`src/main/resources/messages/messages.properties`](src/main/resources/messages/messages.properties) and locale variants - UI text and internationalization resources.
- [`src/checkstyle/nohttp-checkstyle.xml`](src/checkstyle/nohttp-checkstyle.xml) and [`src/checkstyle/nohttp-checkstyle-suppressions.xml`](src/checkstyle/nohttp-checkstyle-suppressions.xml) - style and HTTP-link checks.
- [`gradle/wrapper/gradle-wrapper.properties`](gradle/wrapper/gradle-wrapper.properties) - pinned Gradle wrapper version used by the build.

## Common Patterns
A few conventions show up repeatedly throughout the codebase:

- **Shared base entities**: most domain objects inherit from [`BaseEntity`](src/main/java/org/springframework/samples/petclinic/model/BaseEntity.java), and name-bearing objects extend [`NamedEntity`](src/main/java/org/springframework/samples/petclinic/model/NamedEntity.java).
- **Spring MVC by feature**: controllers, repositories, and domain types are grouped by business area instead of by technical layer alone.
- **Form-first web flows**: create/update handlers validate input, return the same form on error, and redirect on success.
- **Pagination**: list pages commonly use `PageRequest` and page metadata such as `currentPage`, `totalPages`, and `totalItems`.
- **Internationalization**: UI text comes from message bundles, with locale switching supported through web configuration.
- **Environment-specific config**: database and deployment settings are kept in profile properties, Docker Compose, and Kubernetes manifests rather than hardcoded in the app.

## Quick Mental Model
If you are tracing a feature, follow this path:

```mermaid
flowchart TD
Start["Start here"] --> App["PetClinicApplication"]
App --> Model["BaseEntity and NamedEntity"]
App --> Owners["OwnerController"]
App --> Vets["VetController"]
```

A good first change is usually to find the relevant controller, identify the repository it uses, and then trace the domain object back to the shared base classes.