The PR was 14 lines.
The incident cost two days.
Tests passed. Code review approved. Production corrupted customer orders anyway.
Someone refactored OrderService. One method call moved outside DB::transaction().
The email notification failed mid-request.
Half the order was written. Half wasn't.
The diff looked harmless.
The types were correct.
The logic seemed unchanged.
The architecture was not.
The problem I kept running into
Modern Laravel applications rarely execute inside a single file.
A request often flows through:
Route
→ Middleware
→ FormRequest
→ Policy
→ Controller
→ Service
→ Transaction
→ Event
→ Listener
The bigger the application becomes, the harder it is to understand this flow.
Most tooling doesn't help much.
PHPStan verifies types.
Tests verify behavior.
Code review focuses on diffs.
But none of them answer a simple question:
Did the execution architecture of this route change?
For example:
POST /orders
Before:
auth
tenant middleware
DB::transaction
Order::create
OrderCreated event
After:
auth
tenant middleware
Order::create
OrderCreated event
The transaction disappeared.
The code still compiles.
The tests may still pass.
But the architecture has changed.
I wanted architecture to become testable
Frontend teams have snapshot testing.
If a UI unexpectedly changes, CI catches it.
I started wondering:
What if we could do the same thing for execution architecture?
That idea became ArchMind.
Instead of treating a Laravel project as a collection of files, ArchMind builds an execution graph.
Route
→ Middleware
→ Controller
→ Service
→ Transaction
→ Event
The graph becomes a baseline.
Future commits are compared against it.
If an important architectural component disappears, ArchMind reports a topology regression.
Example:
✘ TOPOLOGY REGRESSION: POST /orders
lost:
transaction_boundary
CI fails before the change reaches production.
What ArchMind actually does
1. Trace execution flow
archmind trace --project . "POST /orders"
Output:
POST /orders
└─ auth:sanctum
└─ ResolveTenant
└─ OrderController::store
└─ OrderService::createOrder
└─ DB::transaction
├─ Order::create
└─ OrderCreated
This provides a route-level view of the execution path.
No digging through controllers, services, events, and listeners manually.
2. Detect topology regressions
archmind verify --project .
Example:
✘ TOPOLOGY REGRESSION
Route:
POST /orders
Lost:
transaction_boundary
The goal is not to verify business logic.
The goal is to verify architecture.
3. Surface architecture findings
archmind findings --project .
Examples:
missing_authorization
Route is authenticated
but no authorization layer was detected.
Or:
transaction_escape
Event dispatched from inside
a transaction boundary.
These findings are intentionally conservative.
The idea is to surface architectural risks for review rather than claim guaranteed vulnerabilities.
An unexpected side effect: better AI context
Originally, ArchMind was not built as an AI tool.
It started as a static analysis and architecture verification tool.
But once an execution graph existed, it became useful for retrieval as well.
Most AI coding tools work roughly like this:
Question
↓
Find similar files
↓
Send files to LLM
ArchMind instead retrieves execution context:
Question:
Why does this payment endpoint sometimes double-charge customers?
Relevant context:
- transaction boundary
- payment event dispatch
- after-commit listener
In benchmark tests on real Laravel applications:
| Metric | ArchMind | File Dump |
|---|---|---|
| Correct answers | 3/3 | 1/3 |
| Average score | 76.7% | 61.7% |
| Tokens per query | ~700 | ~9000 |
The interesting result wasn't just higher accuracy.
It was that the execution graph compressed architecture knowledge into a much smaller context window.
How it works
At a high level:
PHP Source
↓
Tree-sitter parsing
↓
Laravel-aware analysis
↓
Execution Graph
↓
Topology Verification
No PHP runtime required.
Current support includes:
- Laravel 10
- Laravel 11
- Laravel 12
- Middleware chains
- FormRequests
- Policies
- Transactions
- Events
- Route groups
- apiResource routes
What ArchMind does not do
It's important to be clear about limitations.
ArchMind will not catch:
- Incorrect business logic
- Off-by-one errors
- Wrong comparison operators
- Runtime bugs caused by external services
It focuses on structural and architectural changes.
Think of it as:
Snapshot testing for execution architecture.
Not a replacement for tests.
Not a replacement for static analysis.
An additional layer that verifies architectural intent.
Example CI setup
Save a baseline:
archmind verify --project . --update
Commit it:
git add .archmind/baselines
git commit -m "chore: add topology baseline"
Then run in CI:
- run: npm install -g @kidkender/archmind
- run: archmind verify --project .
If a transaction boundary disappears, an auth middleware is removed, or a protected route loses part of its architecture, the build fails.
Final thoughts
The most interesting realization from this project wasn't about Laravel.
It was this:
Tests verify behavior.
Architecture usually lives in people's heads.
When architecture becomes a graph, it becomes something we can version, compare, and verify.
That's the idea behind ArchMind.
I'd love feedback from Laravel developers:
- Have architectural regressions caused incidents in your projects?
- How do you currently review execution flow changes?
- Would architecture-level verification be useful in your CI pipeline?
Top comments (0)