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 <java.version>17</java.version>, 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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Produce a report or file, no repo.
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.