# Explain the Architecture of a Spring Boot Codebase An agent reads a Spring Boot codebase, follows one request from controller to JPA repository, and returns an architecture document with diagrams and file references. [Run this on Rush](https://cloud.getrush.ai/run/architecture-overview/spring-boot/), in a Project that has your repository. ## What the agent does The agent begins with the build, not with a diagram guessed from package names. In a Spring Boot app like spring-projects/spring-petclinic, `pom.xml` inherits `spring-boot-starter-parent` 4.1.0 with `17`, and `build.gradle` declares the same Spring Boot plugin version with a Java 17 toolchain, so the document records that both build systems are maintained and which one it ran. The starters tell it what the app is: `webmvc`, `thymeleaf`, `data-jpa`, `validation`, `cache` with Caffeine, and `actuator`, with H2, MySQL and PostgreSQL drivers all present. Then it reads the packages under `src/main/java/org/springframework/samples/petclinic/`. `PetClinicApplication` is the entry point; `model` holds `BaseEntity`, `NamedEntity` and `Person`; `owner` holds `Owner`, `Pet`, `PetType`, `Visit`, their controllers, `OwnerRepository` and `PetTypeRepository`, a `PetValidator` and a `PetTypeFormatter`; `vet` holds `Vet`, `Specialty`, `Vets`, `VetRepository` and `VetController`; and `system` holds `CacheConfiguration`, `WebConfiguration`, `WelcomeController` and the deliberate `CrashController`. The document explains each package's ownership and the rule the package layout follows: one package per aggregate, with the repository and controller beside the entity. The request walkthrough follows one path end to end: an owner search from the Thymeleaf form under `src/main/resources/templates/owners/` into `OwnerController`, through the Spring Data method on `OwnerRepository`, to the SQL Hibernate emits against the schema in `src/main/resources/db/h2/schema.sql`, and back through the template. Along the way it records what `application.properties` sets: `database=h2` with schema and data scripts chosen by that property, `spring.jpa.hibernate.ddl-auto=none`, `spring.jpa.open-in-view=false`, a snake-case naming strategy, `default_batch_fetch_size=16`, and every actuator endpoint exposed. `application-postgres.properties` and `application-mysql.properties` show how the same app runs on a real database, and `docker-compose.yml` provides `mysql:9.7` and `postgres:18.4` for that. To separate observed behavior from static reading, the agent runs the app in the sandbox with `./mvnw spring-boot:run`, opens `http://localhost:8080/` in the browser, performs the owner search it traced, and reads the actuator's `mappings` endpoint for the route table. It also runs `./mvnw test` once and names the test classes that cover each package, such as `OwnerControllerTests`, `ClinicServiceTests` and `PetClinicIntegrationTests`, so a reader knows where behavior is pinned. It changes no code and opens no pull request. ## Start it with one API call `POST https://api.prix.dev/o/{org}/sessions` ```json { "agent": "claude", "input": "Read the attached Spring Boot repository and write architecture.md. Record the commit, the build system and its Spring Boot and Java versions, the starters in use and the entry point. Explain each package's ownership, the JPA entities and their relationships, the repositories, the web layer and templates, caching, configuration profiles and database setup. Trace one representative request from the HTTP form through the controller and Spring Data repository to the SQL and back to the rendered view. Include Mermaid component and request-flow diagrams, with file:line citations and short source quotes for factual claims. Run the app with the documented local command if feasible using the in-memory database, exercise the traced request in the browser, and read the actuator mappings; distinguish observed behavior from static analysis and record any setup failure. Do not change app code, access production, push or open a pull request.", "resources": [ { "url": "https://github.com/your-org/your-app" } ] } ``` 1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token. 2. **Send the request.** POST the body in request.json to https://api.prix.dev/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox. 3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory. ## What comes back `architecture.md` comes back as an artifact on the session, with a download link good for an hour that reading the session again renews. It opens with an orientation summary and the inspected commit, then a component map by package, the request walkthrough, a data-model section with the entity relationships and the schema files they map to, a configuration section covering the three database profiles and the actuator exposure, and a guide to where a new feature would go. The Mermaid diagrams use the class and package names from the code, and every edge in the request-flow diagram names the method behind it with a `file:line` citation. The observed section says what the agent actually ran: the Maven command, the URL it opened, the search it performed, the mappings it read, and the test run, or the error if any of those failed in the sandbox. A reviewer checks the citations against the files, reads the observed section to see what was run rather than inferred, and confirms the clone is clean: no commit, no pull request, no edited file. The transcript holds every command and its output beside the document. ## Run it on every major component change Regenerate the document on a schedule or after a large merge rather than letting it rot. In the console, add an automation to the Project with this prompt and a `schedule` trigger, with `cron` set to the first morning of the month in your `timezone`; each run reads the current default branch and returns a fresh `architecture.md` as its artifact. A GitHub trigger on `pull_request.closed.merged` with `branch_patterns` set to the default branch does the same per merge, with the event added after the prompt. From your own server, `POST /o/{org}/sessions` with this prompt and the repository in `resources` does the same on demand, and a `webhook_url` on the key tells you when the document is ready. ## Why run it on Rush? An architecture document written from reading alone misses what only running shows: which routes the actuator actually maps, which profile is active, whether the documented command still starts the app. The sandbox has a JDK, the Maven wrapper and a browser, so the agent runs the app, performs the traced request and reads the mappings, and the document says which claims were observed and which were read. The result is a file with citations, not a chat answer. Every claim points at a `file:line`, the Mermaid diagrams render in any Markdown viewer, and the transcript keeps the commands and output behind the observed section, so a new engineer can check any sentence against the code on the day they join. ## Frequently asked questions ### Does it build with Maven or Gradle? Whichever the repository provides, preferring the wrapper. PetClinic ships both `mvnw` and `gradlew` with the same Spring Boot version, so the document says it ran `./mvnw spring-boot:run` and notes that the Gradle build exists and mirrors it. ### Can I choose the request that the walkthrough follows? Yes. Name the route or the screen in the prompt and the agent traces that one; otherwise it picks one that crosses the web layer, a repository and a template, such as the owner search. A follow-up message to the same session adds a second walkthrough without rereading the codebase. ### What if the app needs a database the sandbox does not have? The agent uses the in-memory profile when one exists, which PetClinic's default `database=h2` provides. When the only profile needs MySQL or Postgres, it starts that database in the sandbox with Docker from the repository's own compose file, or records the setup failure in the observed section and keeps the rest of the document static. ### Does it rewrite the code or open a pull request? No. The prompt forbids changing app code, pushing or opening a pull request, and the result is the document as a session artifact. If you want the document committed under `docs/`, say so in the prompt and the run opens a pull request containing only that file.