What the agent does
The agent reads the application's actual persistence and job configuration before explaining its Rails conventions. In lobsters/lobsters, Gemfile:8-13 declares Solid Cache, SQLite and Solid Queue. config/database.yml.sample:6-21 separates development databases for primary data, cache, queue and request limiting. The overview uses that configuration instead of assuming a Rails application needs PostgreSQL, Redis or a separate queue service. It records the inspected revision and compares model associations with db/schema.rb before drawing storage relationships.
A concrete request anchors the explanation. config/routes.rb:147 routes /s/:id/(:title) to stories#show; app/controllers/stories_controller.rb:145 looks up a story by short_id. The action then handles merged stories, visibility and canonical URLs before loading comment threads at line 177. The agent follows the controller's StoryFinder concern, relevant model scopes and rendering path to show where a request gains its data and where it may redirect. Authentication and moderator-specific behavior stay visible in the walkthrough rather than disappearing inside a controller box.
The model map follows the relationships the code declares. app/models/story.rb:4-6 associates a story with its user, domain and origin, while lines 32-41 connect comments, tags and voters. app/models/comment.rb:4-16 relates comments to users, stories and parent comments. app/models/vote.rb:4-6 links a vote to a user and story, with an optional comment. The diagram explains those different relationships rather than treating every association as a database foreign key. The agent checks schema constraints separately when describing what storage enforces.
Background work receives its own path through enqueueing and execution. stories_controller.rb:38-46 saves inside a transaction and schedules webmention and story-card work, while app/jobs/create_story_card_job.rb:2-6 selects its queue, limits concurrent work per story and generates the image. config/recurring.yml defines scheduled jobs separately. For runtime context, the agent follows CONTRIBUTING.md and the Docker setup guide, using disposable data only. It records whether the app boots and keeps untested conclusions source-derived; the example's contribution policy also means this task sends no generated patch upstream.
Start it with one API call
POST https://api.prix.dev/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Inspect the attached Rails repository and write architecture.md with the commit, component ownership, database layout, domain relationships, one request traced from route through controller/concerns/models to storage and rendering, plus queued and recurring work. Include Mermaid component and request-flow diagrams; support factual claims with file:line citations and short source quotes. Check actual configuration rather than assuming conventional Rails services. Try the documented development setup only with disposable local data and no external delivery; label runtime observations and static conclusions separately. Respect repository contribution rules: do not modify app code, push, submit a PR or contact production.",
"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 gives a new maintainer a reading order, a map of domain models, the chosen request's call path and a separate account of jobs and recurring work. The report explains why the primary database differs from queue and cache storage, and which files determine those choices. The diagrams distinguish request-time actions, delayed jobs and scheduled commands, with source references attached to the edges a reviewer is most likely to question.
The reviewer checks the story lookup key, visibility branches, model relationships and the point where a job is enqueued. The document includes a setup appendix with real output if local execution succeeds, or the exact limitation when it does not. Rush exposes the report in the session's artifacts and retains the investigation's tool events in its messages. The deliverable is an explanation of the inspected code, not an upstream contribution or a claim about a production environment.
Run it on every maintainer onboarding
Your onboarding workflow can call the sessions API with the repository branch and the subsystem a new maintainer will own. Choose a representative request in the input and ask for a short reading order through its actual files. A follow-up, sent after the first turn finishes, can ask the same session to expand the voting or moderation path.
For a recurring refresh, your scheduler starts a new request when a release changes persistence, caching or job execution. Collect the finished file through a session read or the configured webhook and compare it with the last revision's document. Use a new idempotency key for the new source revision so a previous completed overview is not returned as this release's work.
The use case this job follows, with its automation and trigger: Produce a report or file, no repo.
Why run it on Rush?
Rails conventions provide orientation, but they cannot tell a reader which associations, callbacks and background services this particular app uses. Rush gives the agent a separate sandbox for inspecting those decisions and trying local setup without mixing generated credentials or sample records into a maintainer's working copy. The task stays focused on explanation.
The full record makes the architecture document open to challenge: a reviewer can trace a claim about story visibility or queue placement back to the code and commands the agent used. Separate repositories can receive separate overview sessions within your concurrency allowance. Each report keeps its source revision and verification limits instead of borrowing details from another Rails application.
Frequently asked questions
Will it assume Rails means PostgreSQL and Redis?
The task explicitly asks for the configured services. The Lobsters example uses SQLite along with Solid Cache and Solid Queue. The report reads database and job configuration before naming infrastructure in a diagram.
Can the overview include callbacks and concerns?
Yes, the agent follows the selected request beyond the controller action. Concerns, model scopes and callbacks can explain behavior that a routes-to-models sketch misses. Each relevant relationship needs a source reference so the reader can inspect it.
Will a local run send notifications or webmentions?
The request excludes external delivery and production access. Runtime exploration uses disposable local data with external integrations disabled or isolated. If that cannot be established, the report documents the code path without exercising its side effects.
Does this submit generated code to Lobsters?
No, Lobsters is a public reading example for a separate architecture report. Its contribution guide declines generated code submissions, and this task creates no upstream change. Use the repository resource for your own authorized app when requesting an overview.