PetClinic — an Agentic Engineering Playground

A full-stack PetClinic (Angular SPA + Spring Boot REST API). The domain is incidental — this repo exists to demonstrate AI-assisted / agentic software engineering techniques you can lift into your own projects.

What this repo teaches

• Living kept in sync architecture, kept honest by guardrail tests. Diagrams and specs are generated from the code; ArchUnit + extractor tests fail the build when code and diagram drift apart. See GUARDRAILS.md.
• Snapshot now, diff at review. Committed diagrams stay a clean picture of current reality; the red add/remove delta is computed on demand from two git snapshots (puml-diff), when a human asks for it — see /human-review.
• Diagrams generated from code, rendered from source. .puml files are committed and rendered live via the PlantUML proxy straight off GitHub raw — no build step to view them; each render carries a footer naming its own source (see Architecture diagrams).
• C4 model as versioned Structurizr DSL: stable, human C1/C2 + a code-coupled C3 that is unit-tested against the real packages.
• E2E traces → sequence diagrams. Tempo/OpenTelemetry spans from a browser run are replayed into a PlantUML sequence diagram.
• MCP server hosted by the backend at /mcp (Spring AI) — tools/resources an agent can call.
• Code-first OpenAPI. The spec is extracted from the controllers (OpenApiExtractorTest → openapi.yaml); the frontend’s TS types are regenerated from it. Both drift-checked.
• Hooks + CI backstop + CODEOWNERS. Guardrail hooks run before every push, mirrored as unavoidable CI gates (blocking --no-verify), and compare regenerated content — not file paths — so they can’t be gamed; sensitive files need elder review.
• Observability. Zero-code OpenTelemetry → Grafana LGTM, queryable from Claude Code via mcp-grafana.

For example, this domain class diagram is generated from the code by DomainModelExtractorTest and rendered live from the committed DomainModel.puml — see Architecture diagrams for the rest:

Quickstart

A) Tell your agent: start db,be,fe,grafana

B) Manual: Run in separate terminals:

./start-database.sh   # ⇒ embedded Postgres        :5432
./start-backend.sh    # ⇒ Spring Boot (+OTel, MCP)  :8080
./start-frontend.sh   # ⇒ Angular dev server        :4200
./start-grafana.sh   # ⇒ :3300 (Requires Docker)

No Docker? ./start-tempo.sh instead of ./start-grafana.sh — Tempo alone (one downloaded binary, :3200 + OTLP :4318): no dashboards, but everything the sequence diagrams need.