DEV Community

Duck
Duck

Posted on

I Finally Finished the Architecture Tool I Abandoned 2 Months Ago

#devchallenge #githubchallenge

GitHub “Finish-Up-A-Thon” Challenge Submission

What I Built

Two months ago, I started building an experimental tool called ArchMind.

The idea was simple:

What if software architecture could be tested the same way we test behavior?

In large Laravel applications, a single request often spans multiple layers:

Route
 → Middleware
 → Authentication
 → Controller
 → Service
 → Transaction
 → Event
 → Listener
Enter fullscreen mode Exit fullscreen mode

Tests verify behavior.

Static analysis verifies code quality.

But architectural changes often slip through unnoticed.

A missing DB::transaction(), a removed middleware, or a missing authorization layer can pass tests and code review while still creating production issues.

ArchMind parses Laravel applications into execution graphs and helps developers:

  • Visualize execution flows
  • Detect architecture findings
  • Track architectural drift
  • Prevent topology regressions in CI
  • Provide execution-aware context for AI assistants

The project is open source and available on npm:

npm install -g @kidkender/archmind
Enter fullscreen mode Exit fullscreen mode

GitHub:

https://github.com/Kidkender/archMind

npm:

https://www.npmjs.com/package/@kidkender/archmind

Demo

Trace a Route 

archmind trace --project . "POST /orders"
Enter fullscreen mode Exit fullscreen mode

Output:

POST /orders
└─ auth:sanctum
   └─ ResolveTenant
      └─ OrderController::store
         └─ OrderService::createOrder
            └─ DB::transaction
               ├─ Order::create
               └─ OrderCreated
Enter fullscreen mode Exit fullscreen mode

Detect Architecture Regressions 

archmind verify --project .
Enter fullscreen mode Exit fullscreen mode

Example:

✘ TOPOLOGY REGRESSION

Route:
  POST /orders

Lost:
  transaction_boundary
Enter fullscreen mode Exit fullscreen mode

This catches situations where important architectural guarantees disappear during refactoring.

CI Integration 

- run: npm install -g @kidkender/archmind
- run: archmind verify --project .
Enter fullscreen mode Exit fullscreen mode

If a transaction boundary, authentication layer, or tenant isolation mechanism disappears, CI fails immediately.

📸 Insert screenshot: archmind trace

📸 Insert screenshot: archmind verify

The Comeback Story

When I originally started ArchMind, it was little more than an experiment.

It could parse Laravel routes and generate a basic execution graph.

That was interesting, but not useful enough for real projects.

At that point the project was missing almost everything required to be practical.

Before

❌ No topology regression detection

❌ No architecture findings

❌ No CI integration

❌ No retrieval benchmarks

❌ No npm package

❌ No real-world validation

The project sat unfinished while I worked on other things.

A few months later I revisited the idea after encountering a production issue caused by an architectural change that passed both tests and code review.

That experience convinced me there was still something worth pursuing.

What I Added

Over the following months I completed:

  • Execution graph engine
  • Architecture findings system
  • Topology regression detection
  • CI workflows
  • Retrieval engine improvements
  • Benchmark suite
  • npm publishing
  • Documentation

Results

Retrieval recall improved from:

0.71 → 1.00
Enter fullscreen mode Exit fullscreen mode

Architecture QA benchmark:

Method Score
ArchMind 76.7%
File-based retrieval 61.7%

Token usage reduction:

Up to 15.6× smaller context
Enter fullscreen mode Exit fullscreen mode

Most importantly, the project evolved from a prototype into something developers can actually install and use.

📸 Insert screenshot: benchmark table

📸 Insert screenshot: npm package page

My Experience with GitHub Copilot

GitHub Copilot played a significant role in helping me finish the project.

One of the hardest parts of reviving an older codebase is rebuilding momentum.

After several months away from ArchMind, there were many areas where I needed to quickly re-familiarize myself with the implementation.

Copilot helped by:

Accelerating Refactors

Large portions of the execution graph engine required repeated traversal and visitor patterns.

Copilot generated boilerplate structures that I could adapt rather than writing everything from scratch.

Expanding Test Coverage

Copilot helped generate test scaffolding and edge-case scenarios that I later refined and validated manually.

This made it easier to improve confidence while evolving the architecture.

Documentation and Examples

Many CLI examples, usage snippets, and documentation sections were drafted with Copilot assistance and then edited for accuracy.

Reducing Context Switching

Most importantly, Copilot reduced the friction of returning to an unfinished project.

Instead of spending hours reconstructing implementation details, I could iterate faster and focus on the architectural ideas behind the tool.

What I Learned

The biggest lesson from finishing ArchMind is that architecture itself can be treated as data.

Once architecture becomes a graph, it becomes possible to:

  • Version it
  • Query it
  • Compare it
  • Verify it

That realization transformed ArchMind from an abandoned side project into a tool that developers can use to protect architectural intent in production systems.

Tests verify behavior.

ArchMind verifies architecture.

Links

GitHub

https://github.com/Kidkender/archMind

npm

https://www.npmjs.com/package/@kidkender/archmind

Top comments (0)