What the agent does
The agent starts where the solution starts. In a services-based application like dotnet/eShop, global.json pins the .NET SDK to 10.0.302 and the MSTest.Sdk to 4.0.2, and src/eShop.AppHost/AppHost.cs is the composition root: it adds Redis, a RabbitMQ container named eventbus with a persistent lifetime, a PostgreSQL container from the ankane/pgvector image with four databases (catalogdb, identitydb, orderingdb, webhooksdb), then registers identity-api, basket-api, catalog-api, ordering-api, order-processor, payment-processor, webhooks-api, a YARP reverse proxy named mobile-bff, webhooksclient and webapp, each with WithReference and WaitFor calls that say which resources it depends on. The agent reads that file first because it is the dependency graph in code, and src/eShop.AppHost/Extensions.cs, which configures the mobile BFF routes and the optional Foundry and Ollama models, second.
Then it reads each service's Program.cs and the shared defaults. src/eShop.ServiceDefaults/Extensions.cs adds health checks, OpenTelemetry metrics and tracing with ASP.NET Core, HttpClient, gRPC client and runtime instrumentation, service discovery, and a standard resilience handler on every HttpClient. Catalog.API is minimal APIs with versioning and OpenAPI, its routes in src/Catalog.API/Apis/CatalogApi.cs (/items, /items/by, /items/{id}/pic, /items/withsemanticrelevance on v1 and v2); Basket.API is a gRPC service defined in src/Basket.API/Proto/basket.proto with GetBasket, UpdateBasket and DeleteBasket, stored in Redis; Identity.API is Duende IdentityServer 7.3.2 over ASP.NET Identity with the clients listed in Configuration/Config.cs (maui, webapp, webhooksclient and three Swagger UI clients); WebApp is Blazor with interactive server components that talks to the basket over gRPC and to catalog and ordering over versioned HTTP clients.
The ordering side gets the deepest read because it carries the domain model. src/Ordering.Domain/AggregatesModel/ holds the Buyer and Order aggregates and seven domain events; src/Ordering.API/Application/ holds MediatR commands such as CreateOrderCommand and CancelOrderCommand with their handlers, the LoggingBehavior, ValidatorBehavior and TransactionBehavior pipeline, FluentValidation validators and domain event handlers; src/Ordering.Infrastructure/ holds OrderingContext, entity configurations, an Idempotency folder with RequestManager and four EF migrations starting at 20230925222426_Initial. Integration events cross services through src/EventBus/ abstractions and src/EventBusRabbitMQ/RabbitMQEventBus.cs, which publishes to the eshop_event_bus exchange with a Polly retry pipeline and propagates OpenTelemetry context; IntegrationEventLogEF is the outbox.
With that map the agent traces one order: the Blazor checkout calls OrderingService, the API's CreateOrderCommand runs through the three behaviours, the OrderStartedDomainEvent validates or creates the buyer, OrderProcessor's GracePeriodManagerService fires GracePeriodConfirmedIntegrationEvent, Catalog.API confirms or rejects stock, PaymentProcessor answers with payment succeeded or failed, and WebApp renders the status change it receives from its own event bus subscriptions. The document cites file:line for each hop, distinguishes what it observed by running aspire run or the functional tests under tests/ from what it read statically, and includes Mermaid component and sequence diagrams. It changes nothing 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 this ASP.NET Core solution and write architecture.md. Start from global.json, the solution filter files and src/eShop.AppHost/AppHost.cs; list every resource and project the AppHost registers with its references and wait-for dependencies. Then read src/eShop.ServiceDefaults and each service's Program.cs and extension methods: record the protocol each service speaks (HTTP, gRPC, RabbitMQ), its database, its authentication, and the packages it relies on from Directory.Packages.props. Read Ordering.Domain, Ordering.API/Application and Ordering.Infrastructure in full and explain the aggregates, the MediatR behaviours, the outbox and the idempotency handling. Trace one order from the Blazor checkout through the ordering API, the grace period processor, the catalog stock check and the payment processor back to the web app, with file:line citations and short quotes. Include a Mermaid component diagram and a Mermaid sequence diagram. If the container runtime is available, run aspire run or the functional tests under tests/ to confirm the flow and say what you observed versus what you read; if not, say so. Do not change code, 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
What comes back is architecture.md as an artifact on the session. It opens with the SDK version and the commit it read, then a table of the resources and projects from AppHost.cs with their dependencies, a section per service naming its protocol, store, auth and entry file, a section on the ordering domain with the aggregates, behaviours, outbox and idempotency, and the traced order with a citation for each hop. The two Mermaid diagrams render in GitHub and in the console's Markdown view.
The transcript at GET /o/{org}/sessions/{id}/messages lists every file the agent opened and, if it ran the AppHost or the functional tests, each command with its output, so a reader can tell an observed claim from a static one. The repository is not changed and the session lists no pull request.
Before sharing the document, a reviewer checks the sequence diagram against src/Ordering.API/Application/IntegrationEvents/EventHandling/ and the subscriptions in each service's AddEventBusSubscriptions, which is where a missed event shows up, and decides whether the Foundry and Ollama options, off by default in AppHost.cs, belong in the main diagram or in an appendix.
Run it on every major component change
Create an automation in the Project with this prompt and a github trigger on pull_request.closed.merged with branch_patterns matching your default branch, and a config.labels filter such as architecture, so a merged pull request carrying that label regenerates the document. The trigger adds the pull request event after the prompt and fills in no placeholder; the artifact on each run's session is the new version.
From your own server, the same run starts with POST /o/{org}/sessions and this body after a release, with a request_id, one UUID kept per tag, so a retried call returns the first run. Read the artifact URL from GET /o/{org}/sessions/{id} or from the run.completed webhook on the key.
The use case this job follows, with its automation and trigger: Produce a report or file, no repo.
Why run it on Rush?
Reading eShop properly means the .NET 10 SDK, a container runtime for PostgreSQL, Redis and RabbitMQ, the Aspire CLI and time to follow an order across nine projects. On Rush that happens in a sandbox with its own clone, the commands run there and their output is kept, so the document can say "observed" about a flow because the transcript shows the run that observed it.
The document carries citations and the session carries the proof, which is what makes it something a new team member can trust and an owner can correct. Several solutions, or several branches of this one, can be documented at the same time in separate sandboxes.
Frequently asked questions
Will it explain the MAUI and hybrid clients too?
It records src/ClientApp and src/HybridApp as clients of the mobile-bff YARP proxy and the maui client in Identity.API, and reads their service layers for the endpoints they call. It does not build the MAUI workloads, and it says so; the server trace is the part it can observe.
Can I choose the request that the diagram follows?
Yes. Replace the order checkout in input with another flow, such as a catalog search with semantic relevance through Catalog.API or a webhook subscription through Webhooks.API, and the sequence diagram follows that one instead.
What happens if Docker is not available in the sandbox?
The document is written from the code alone and every claim is marked as static analysis. The prompt asks the agent to say so explicitly rather than describe a run it did not make.
Does it rewrite code or open a pull request?
No. The output is the Markdown file on the session. If you want the document committed under docs/, a follow-up on the same session can open a pull request with it.