Tests Verify Behavior. ArchMind Verifies Architecture.

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:

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?

GitHub: https://github.com/Kidkender/archMind