How We Eliminated Architectural Drift by Building ArchGuard

The Scaling Wall

If you have ever watched a fast growing engineering team expand across multiple projects, you have seen the exact moment project structure breaks down. Early on, everyone follows the same setup. But as teams multiply, developers naturally build things in different ways, creating architectural drift, four different applications using four completely different folder structures, state management patterns, and import rules.

At Aviato Consulting, code reviews started slowing down because senior engineers spent more time debating where files belonged than reviewing actual feature logic. Even worse, hardcoded API keys and JWT tokens were occasionally slipping into code commits due to a lack of automated checks.

We needed a simple way to standardize project structures and enforce architectural boundaries across Flutter, React, and Node.js without slowing down our development speed.

The Hidden Cost

When projects lack standard folder structures and automated boundary checks, codebases quickly turn into a confusing mess where layers leak into each other.

The Unchecked Commit Scenario:

Imagine a developer accidentally imports a private database access layer directly into a frontend UI component, while also leaving a GCP secret key in the config file. Without automated checks, this pull request gets merged, breaking system boundaries and exposing critical cloud keys in the source repository.

Discovery

When our engineering team set out to solve this during an internal 48 hour company hackathon, we started by looking at how developers create new projects.

We noticed that teams were copying and pasting older repositories to start new services. This copied outdated folder structures, unused code, and bad habits across every new codebase.

Why Quick Fixes Failed

Relying only on pull request reviews and documentation guides did not work for us:

• Manual reviews miss things
  Human reviewers get tired and focus on business features, easily missing incorrect folder placements or leaky imports.
• Documentation gets ignored
  Static setup guides sitting in a wiki quickly become outdated, and developers rarely check them during daily coding tasks.
• Build friction causes frustration
  Blocking builds for minor folder layout errors frustrates developers and slows down feature delivery.

The Structural Flaw

The root cause of our architectural drift was the gap between what project documentation recommended and what developers actually built.

Without an automated tool to generate standard structures and scan code locally, developers had to guess the right setup. To fix this, we needed a simple two part workflow: automated scaffolding to set up projects correctly, combined with automated scanning to catch errors early.

The Blueprint

During the hackathon, we built ArchGuard, a lightweight command line interface (CLI) tool created with Node 18 and TypeScript using Commander, Inquirer, Chalk, and ShellJS.

To keep the tool fast, we used regular expressions instead of complex Abstract Syntax Tree (AST) parsers. This allowed us to support Node.js, Flutter, and Python out of the box.

1. archguard init(The Carrot)

When starting a project, developers run archguard init. The interactive CLI asks about the stack and generates a complete, clean project structure. It leaves behind a .archguardrc.json configuration file that acts as the single source of truth for that codebase’s architecture rules.

2. archguard scan(The Stick)

Developers or CI pipelines run archguard scan to check three key areas:

• **Directory Integrity
  **Confirms that all mandatory folders exist.
• **Import Boundaries
  **Ensures layers stay separate (for example, stopping UI layers from importing private domain models).
• **Secrets Detection
  **Scans files to catch exposed API keys or tokens before code merges.

Proving the Solution

To ensure teams adopted ArchGuard smoothly, we added it to our Bitbucket Pipelines as a non blocking step. This lets teams see rule violations in their build logs without stopping their active deployments.

Step 1: Scaffolding Setup

Developers run archguard init to create a standard project structure with an embedded .archguardrc.json config file.

Step 2: Local & CI Scanning

The archguard scan command runs locally or during builds to check folder layouts and verify import rules using regular expressions.

Step 3. Automated Secrets Check

The scanner inspects code files for exposed JWT tokens or cloud credentials before code gets merged into shared branches.

Step 4. Non Blocking CI Logs

Bitbucket Pipelines run the scan and display violations directly in build logs, allowing teams to fix drift voluntarily without breaking active builds.

## Bitbucket Pipeline Integration
pipelines:
  default:
    - step:
        name: ArchGuard Compliance Scan
        image: node:18
        script:
          - npm install -g archguard
          - archguard scan
          - echo "Scan completed. Check logs for architectural drift."

Practical Takeaways

Clear standards combined with automated checks eliminate project chaos.

ArchGuard grew from a third place hackathon project into an official engineering standard across our company. By combining automated project setup with non blocking scans, we cut down code review friction and caught security risks early.

Action Plan for Growing Teams

If your team is dealing with inconsistent project structures, follow these practical steps:

1. **Automate Project Setup
   **Create a simple CLI or template generator so developers always start with an audited project structure.
2. **Define Rules in Code
   **Keep architectural rules inside a version controlled file (like .archguardrc.json) inside the repository itself.
3. **Start with Soft Enforcements
   **Add architectural scans to your CI pipeline as non blocking steps first, helping teams fix issues without stopping active deployments.