# Write an Architecture Overview of a Filament Admin Panel

Yes. An agent reads your Filament panels, resources, models and tests and writes an overview a new engineer can start from, with every claim tied to a file.

[Run this on Rush](https://cloud.getrush.ai/run/architecture-overview/filament/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

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.phoenix.so/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 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.

## 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.

## More Filament jobs

- [Dockerize a Filament App](https://getrush.ai/run/dockerize-app/filament/)
- [Upgrade Filament and Composer Dependencies](https://getrush.ai/run/upgrade-composer-dependencies/filament/)
- [Write Tests for a Filament Admin Panel](https://getrush.ai/run/write-filament-tests/filament/)

## The same job on other stacks

- [Explain the Architecture of a Go Codebase](https://getrush.ai/run/architecture-overview/go/)
- [Explain the Architecture of a Rails Codebase](https://getrush.ai/run/architecture-overview/rails/)
- [Explain the Architecture of a Spring Boot Codebase](https://getrush.ai/run/architecture-overview/spring-boot/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
