# Explain the Architecture of an ASP.NET Core Solution Yes. An agent reads an ASP.NET Core solution from its Aspire AppHost to each service, traces one order end to end, and returns a cited architecture document. [Run this on Rush](https://cloud.getrush.ai/run/architecture-overview/aspnet-core/), in a Project that has your repository. ## 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` ```json { "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" } ] } ``` 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 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. ## 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.