What the agent does
The agent clones the app and starts with the panels, because in Filament the panel providers are the map. In an app like filamentphp/demo, composer.json requires filament/filament ^5.0 with the Spatie media library, settings and tags plugins, laravel/framework ^12.0, laravel/octane and laravel/sanctum, and for development pestphp/pest ^3.0, larastan/larastan, laravel/pint and rector/rector; the setup script copies .env.example, generates a key, touches database/database.sqlite, migrates, seeds and links storage. app/Providers/Filament/AdminPanelProvider.php declares the default panel with id admin: it discovers clusters, resources, pages and widgets under app/Filament, orders the navigation into Shop, HR, Projects and Blog, turns on database notifications, SPA mode and Cmd+K global search, and uses a custom Login page under app/Filament/Pages/Auth. AppPanelProvider.php declares a second panel at /app with registration, password reset and email verification, tenancy on the Team model with a RegisterTeam page, and its own discovery paths under app/Filament/App. routes/web.php adds only a Livewire Form route and a login-redirect; everything else is a panel route.
Then it walks what each panel discovers. app/Filament/Resources holds three groups: Shop with Brands, Categories, Customers, Orders and Products; Blog with Authors, Categories and Posts; and HR with Departments, Employees, Expenses, LeaveRequests, Projects, Tasks and Timesheets. Each resource follows the same layout, a Resource class, Pages, Schemas with a form and often an infolist, Tables, and where needed RelationManagers and Widgets, so the overview describes the pattern once and lists the exceptions: Authors and the two Categories resources use a single Manage page with modals, Posts has View, Edit and ManagePostComments pages behind sub-navigation, and Orders carries an OrderStats widget and a PaymentsRelationManager. The fourteen widgets under app/Filament/Widgets feed three dashboards, Dashboard, ShopDashboard and HrDashboard, and Exports and Imports hold the CSV exporters for authors and brands and the importers for both category models.
The data layer comes next. app/Models mirrors the groups: Shop with Order using SoftDeletes and an OrderStatus enum cast, OrderItem, OrderAddress, Payment, Product, ProductCategory, Brand and Customer; Blog with Post, Author and PostCategory; HR with eight models from Department to ExpenseLine; and the shared Address, Comment, Team and User, where User implements FilamentUser and HasTenants and today answers true to canAccessPanel and canAccessTenant and returns every team from getTenants. The thirteen enums under app/Enums carry the statuses and types the forms and tables switch on. database/migrations holds 37 numbered files in dependency order, from users and media through orders, payments, the polymorphic addressable table, teams, Filament's import and export tables, and the HR tables last; database/seeders/DatabaseSeeder.php builds the demo data with factories under database/factories, and app/Console/Commands/ResetDemoDatabase.php rebuilds it by preparing a fresh Postgres schema and swapping it in under a cache lock. AppServiceProvider calls Model::unguard(), which the overview flags, because it means no model has a fillable guard.
Finally it reads how the app is checked and writes the document. tests/Pest.php binds every test under tests/Filament to RefreshDatabase and an authenticated factory user; the suite has one test file per resource page, one per widget and one for the two dashboards, and .github/workflows/tests.yml runs composer test:pest on PHP 8.4 with SQLite after npm run build, while phpstan.yml runs Larastan and format.yml commits Pint fixes on the release branch. The overview, architecture.md, has sections for the two panels and their auth, the resource pattern and its exceptions, the dashboards and widgets, the models, enums and migrations, the seeding and reset path, the test and CI setup, and a closing list of things a new engineer should know before changing anything: the unguarded models, the open canAccessPanel, and the two panels sharing one Login page. Every paragraph cites the file it came from, and the agent runs composer install and composer test:pest in the sandbox first so the class names it cites resolve and the suite's shape is what it describes.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Write an architecture overview of this Filament admin panel as architecture.md. Read composer.json, routes/web.php, app/Providers/AppServiceProvider.php, every file under app/Providers/Filament, the directory trees of app/Filament, app/Models, app/Enums, database/migrations, database/factories and database/seeders, app/Console/Commands, app/Models/User.php, tests/Pest.php, tests/TestCase.php, phpunit.xml and every workflow under .github/workflows. Run composer install and composer test:pest first so the class names you cite exist and the test shape is real. Describe each panel and how it authenticates and discovers resources, pages and widgets; the resource layout pattern once and every resource that departs from it; the dashboards and which widgets they show; the models grouped as the resources are, with soft deletes, enum casts and tenancy called out; the migration order and the seeding and reset commands; and the test and CI setup. End with a list of things a new engineer must know before changing the app, such as unguarded models or open panel access. Cite the file for every claim. Do not change any file.",
"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.phoenix.so/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 one file, architecture.md, as an artifact on the session, with a download link that works for an hour and is refreshed on every read of the session. It reads top down: panels and auth, the resource pattern and its exceptions, dashboards and widgets, models, enums and migrations, seeding and the reset command, tests and CI, and the closing list of things to know. Every paragraph names the file it came from.
The session's result field holds the short version: how many resources, widgets, models and migrations the app has, which panel is the default, and the two or three facts from the closing list that matter most. The transcript shows the composer install and composer test:pest runs and each file read as tool_use events, so a reader can check that the suite ran before the overview described it.
A reviewer reads the closing list first, then spot-checks a resource section against its Resource class and the tenancy paragraph against User.php. The file goes into the repository's docs or a wiki by hand; the run writes nothing to the branch.
Run it on every first of the month
Add an automation to the Project with this prompt and a schedule trigger with cron set to the first of the month at 07:00 in the team's timezone. Each fire starts a run on the default branch and writes a fresh overview from the code as it is, so a resource added in week two is in the next document rather than in a stale wiki page. Set the automation to read only, since this job changes nothing.
For an overview tied to a release, send POST /o/{org}/sessions with this body from the release script with a request_id that is a UUID v5 of the tag, so a rerun returns the same run, and give the key a webhook_url so run.completed arrives with data.session_url to fetch the artifact from.
The use case this job follows, with its automation and trigger: Produce a report or file, no repo.
Why run it on Rush?
A Filament app's architecture is spread across panel providers, resource directories, model groups and enums, and the honest overview is the one that reads all of it and runs the suite so the class names resolve. In a Rush sandbox the agent installs with Composer, runs pest, reads every provider, resource and model, and keeps each read and command in the run's record, so the document carries its evidence rather than a summary of the README.
Because the run needs only the repository, a SQLite file and the commands the repository already defines, it finishes with a file and a summary and never touches a branch. The same request runs against several Filament apps at once, each in its own sandbox, each returning its own architecture.md.
Frequently asked questions
Does it describe Filament itself or my app?
Your app. The overview names the Filament features the app uses, tenancy, clusters, relation managers, importers, because those shape the code, but it explains them only as far as the app's own files use them, with a citation each time. Framework internals stay out.
Why run the tests for a document?
Two reasons. The class names and page types the overview cites must exist on the branch it read, and composer install plus pest is the cheapest proof. And the test layout, one file per resource page and widget, is itself part of the architecture a new engineer needs to know.
Will it flag problems or only describe?
It ends with a short list of facts that change how you should work in the app: Model::unguard() in the service provider, canAccessPanel returning true for every user, and the tenancy that returns every team. It does not propose fixes; a follow-up message to the session can ask for them on a branch.
Can it draw a diagram?
Ask for a Mermaid block in the prompt and the overview includes one for the panel, resource and model relationships, written from the same files. Mermaid renders in GitHub and most wikis; the Markdown stays readable without it.