What the agent does
The agent begins with the module declaration and executable entry points, not a diagram guessed from directory names. In pocketbase/pocketbase, go.mod:1 declares github.com/pocketbase/pocketbase, while examples/base/main.go:20 constructs the app with pocketbase.New(). That example registers JavaScript hooks, migrations and self-update plugins before app.Start() at line 119. The overview distinguishes the reusable library from this standalone executable. It records the inspected commit so later readers know which version of the architecture the explanation describes.
It traces a concrete request through registration, middleware, query construction and response handling. apis/base.go:39-49 creates the /api group and binds record, file, realtime and other API families. apis/record_crud.go:27-33 registers collection record operations; its list handler checks the collection's ListRule, builds a query and applies the rule expression before executing the search. core/record_query.go:38 constructs that query through ConcurrentDB(). These references support a request-flow diagram whose arrows describe actual calls, including authorization filtering and response hooks.
The data-model section explains collection metadata separately from individual records. core/collection_model.go:358-374 defines the collection's operation rules, name, type, fields and indexes. core/base.go:49-50 names data.db and auxiliary.db, and core/db.go:65-74 distinguishes their query helpers. The agent follows the relevant initialization and model code before explaining what each database stores. It also separates HTTP handling from scheduled work: core/base.go:1433-1452 starts the app cron service on serving and registers a database-maintenance job.
The agent reads README.md, the Go requirement and plugin setup before attempting a local run. The README identifies examples/base as the standalone example; plugins/jsvm/jsvm.go:128-145 resolves the hook and migration directories during plugin registration. If the toolchain and documented setup are available, it runs a local example with disposable state and records the observed startup and a harmless request. If they are unavailable, architecture.md labels its conclusions as source-derived. The job changes no application code and does not publish anything to the example repository.
Start it with one API call
POST https://api.prix.dev/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Read the attached Go repository and write architecture.md. Record the commit, module and executable entry points; explain component ownership, data models, storage, background work and extension points. Trace one representative request from registration through middleware and authorization to database query and response. Include Mermaid component and request-flow diagrams, with file:line citations and short source quotes for factual claims. Follow the documented local example if feasible using disposable sandbox state; distinguish observed behavior from static analysis and record setup failures. Do not change app code, access production, push or open a PR.",
"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 contains an orientation summary, a component map, an end-to-end request walkthrough, a data-model explanation, a background-work section and a guide to extension points. The Mermaid diagrams use the same names as the code and cite the functions behind important edges. For the PocketBase example, the document distinguishes app construction, HTTP routing, core persistence and optional plugin registration rather than flattening everything into one backend box.
The reviewer follows the selected request through the cited files and checks that each diagram arrow represents a call or dependency the source supports. Unresolved questions, runtime observations and source-only conclusions have separate labels. The session returns the document as an artifact and its answer explains any limits; the transcript provides command output for the local checks that actually happened. This task supplies an onboarding document, with no claim that a run has already produced a particular result.
Run it on every major component change
Your repository webhook receiver can submit an overview request when entry points, persistence or background processing change. Use a branch-specific GitHub resource and include the question the reviewer needs answered, such as which layer owns record filtering. Start a fresh session for each revision and reuse its Idempotency-Key only for delivery retries.
A scheduler can also request an onboarding refresh at a regular interval. Read the completed session or use the key's configured webhook, then keep the resulting document with its inspected commit. Compare diagrams and ownership changes before adopting the new overview; repeated prose is less useful than an accurate explanation of the changed path.
The use case this job follows, with its automation and trigger: Produce a report or file, no repo.
Why run it on Rush?
A useful Go overview requires following interfaces, concrete implementations and startup wiring together. Rush gives the agent its own sandbox to inspect the module graph and try the documented example without modifying a developer's current workspace or reusing an existing application data directory. Any temporary runtime state belongs to this investigation.
The record of commands and outputs lets a maintainer separate a verified startup from an inferred design. You can submit overviews for different repositories within your concurrency limit and receive independent artifacts. Each document remains tied to its source revision, rather than becoming a confident explanation assembled from several unrelated local checkouts.
Frequently asked questions
Will the document explain libraries as well as the executable?
Yes, the request asks the agent to identify both module boundaries and entry points. PocketBase's base example shows why the distinction matters: the executable selects plugins around a reusable app. The overview describes that wiring rather than assuming every package is a service.
Can I choose the request that the diagram follows?
Name the route or operation in input. A record-list request is useful for the example because it crosses routing, collection rules, query construction and response hooks. A focused path gives reviewers a concrete way to verify the explanation.
What happens if the required Go toolchain is missing?
The agent checks the module's declared requirement before attempting execution. It records a setup failure if the documented example cannot run. The architecture document can still cite source, but must not describe a successful live request without evidence.
Does it rewrite the code or create an upstream PR?
This job writes a separate report and leaves application code alone. It does not push or open a pull request on the public example repository. Any later refactor is a different request with its own scope and verification.