Living documentation
Generate Markdown documentation of the real architecture, straight from the code:
php artisan cordon:docs # writes docs/architecture/
php artisan cordon:docs --output=docs/modulesThe output folder (docs/architecture by default, relative to the project root) is created if it doesn't exist. Commit it: the diffs show how the architecture changes.
| File | Content |
|---|---|
README.md | Every module with its namespace, dependencies, users and violation count, and a Mermaid diagram of the dependencies. Edge labels count the classes used; edges with internal access are red. |
modules/<Module>.md | A canvas per module: its description and owner (from metadata), namespace, path, depends_on, a diagram of the module and its neighbours, its components grouped by Laravel role, its public API, the classes it uses from other modules and the ones other modules use from it (internal ones flagged), its events and its violations. |
events.md | Every module event with the classes that publish and listen to it. |
GitHub and GitLab render the Mermaid diagrams. The output is deterministic (sorted, no timestamps), so you can commit it and see architecture changes in pull request diffs.
flowchart LR
m0["Billing"]
m1["Orders"]
m2["Shipping"]
m0 -->|1| m1
m1 -->|1| m0
m2 -->|1| m0
m2 -->|2| m1
linkStyle 3 stroke:#d33,stroke-width:2pxComponents and metadata
Each canvas groups the module's classes by role: Models, Controllers, Commands, Jobs, Listeners, Events, Policies, Notifications, Mail and Other. A known Laravel parent class decides first (a class that extends Illuminate\Database\Eloquent\Model is a model wherever it lives), then a namespace segment (Listeners, Jobs...), then ShouldQueue for jobs.
Describe a module and name its owner in config/cordon.php; the canvas shows them at the top:
'modules' => [
'Billing' => ['metadata' => ['description' => 'Invoices and payments.', 'owner' => 'payments-team']],
],Events
Events are detected statically:
- classes under a module's
Eventsnamespace; - classes dispatched with
event(new X),broadcast(new X),$dispatcher->dispatch(new X)orEvent::dispatch(new X); - classes registered with
Event::listen(X::class, ...).
Publishers also include X::dispatch() and listeners include handle(X $event) / __invoke(X $event), but only for classes that are already events, because jobs use the same method names.
String event names and wildcard listeners are not detected.
Violations
The documentation shows every violation, ignoring the baseline: it describes the code as it is.