Install

npm install -g jimmy007bond-archguard

Usage

archguard
archeck

archguard and archeck are the same CLI entrypoint.

Running archguard opens an interactive terminal shell:

ArchGuard v0.1.7
Type `help` to see commands. Type `exit` to quit.
archguard>

From there you can run:

• help
• analyze
• analyze <projectPath>
• doctor
• version
• serve
• exit

When you run analyze with no path, ArchGuard asks:

Trust this folder and continue? [y/N]

Answer y to analyze the current folder.

🛡️ ArchGuard

Enforce Architecture. Not Opinions.

A Gradle plugin that lets senior engineers define architectural rules and automatically validates every build.

ArchGuard MCP

ArchGuard MCP packages the existing analyzer as a local MCP server for Cursor, Claude Desktop, and other MCP-compatible clients.

npm Launcher

Install the launcher globally:

npm install -g archguard

Use it from the command line:

archguard
archeck
archguard analyze
archguard analyze ../MyApp
archguard doctor
archguard version
archguard help
archguard serve

archguard and archeck are the same CLI entrypoint.

On Windows, archguard with no arguments prompts in the terminal to trust the current folder before analysis starts.

Quick Start

1. Build the distribution:

./gradlew :archguard-mcp:build

2. Start the server:

./gradlew :archguard-mcp:run

3. Configure your MCP client using the examples in INSTALL.md.

Installation

See INSTALL.md for platform-specific installation and client setup.

Supported Tools

• analyze_project
• server_info
• health

Example Prompts

• Analyze my Android project
• Analyze sample-project
• List architecture violations

Troubleshooting

See INSTALL.md.

Why ArchGuard?

Every engineering team has architecture guidelines.

But those guidelines usually live in:

• Documentation
• Wiki pages
• Pull request comments
• Senior engineers' heads

Eventually someone accidentally breaks the architecture.

Not because they're careless.

Because architecture isn't executable.

ArchGuard changes that.

Instead of saying:

"Presentation should never depend on Data."

You define it once.

Then every build enforces it automatically.

Features

✅ Gradle Plugin

✅ Custom Architecture DSL

✅ Configurable Package Structure Rules

✅ Console Reports

✅ JSON Reports

✅ Team-wide Architecture Validation

Example

Instead of documenting your architecture...

feature

    login

        presentation

        domain

        data

Make it executable.

archGuard {
    reports {
        html {
            enabled = true
            outputPath = "archguard-report.html"
        }
    }

    architecture {
        featureRoot = "feature"

        feature("login") {
            requiredLayer("presentation")
            requiredLayer("domain")
            requiredLayer("data")

            feature("chat") {
                requiredLayer("ui")
                requiredLayer("socket")
            }
        }

        forbid(
            "helper",
            "util",
            "manager"
        )
    }
}

Running ArchGuard MCP

Build

./gradlew :archguard-mcp:build

Run

./gradlew :archguard-mcp:run

Expected console output

ArchGuard MCP Server started...

Claude Desktop

Use the installed launcher as the MCP command. On Windows:

{
  "mcpServers": {
    "archguard": {
      "command": "cmd",
      "args": [
        "/c",
        "C:\\Users\\NIZAMUDDIN\\IdeaProjects\\ArchitectureLinter\\archguard-mcp\\build\\install\\archguard-mcp\\bin\\archguard-mcp.bat"
      ]
    }
  }
}

Cursor

Use the same MCP server entry:

{
  "mcpServers": {
    "archguard": {
      "command": "cmd",
      "args": [
        "/c",
        "C:\\Users\\NIZAMUDDIN\\IdeaProjects\\ArchitectureLinter\\archguard-mcp\\build\\install\\archguard-mcp\\bin\\archguard-mcp.bat"
      ]
    }
  }
}

Example prompt

Analyze C:\Users\NIZAMUDDIN\IdeaProjects\ArchitectureLinter\sample-project

Now simply run

./gradlew architectureCheck

Output

Exports as html report plus sample output

==================================
ArchGuard
==================================

Loading Architecture...

✓ login

✗ profile

Missing required layer

domain

----------------------------------

Summary

Features Checked : 2

Passed : 1

Failed : 1

Violations : 1

Feature-centric DSL

archGuard {
    reports {
        html {
            enabled = true
            outputPath = "archguard-report.html"
        }
    }

    architecture {
        featureRoot = "feature"

        feature("login") {
            requiredLayer("presentation")
            requiredLayer("domain")
            requiredLayer("data")

            feature("chat") {
                requiredLayer("ui")
                requiredLayer("socket")
            }
        }

        forbid(
            "helper",
            "util",
            "manager"
        )
    }
}

Legacy DSL

archGuard {
    reports {
        html {
            enabled = true
            outputPath = "archguard-report.html"
        }
    }

    architecture {
        featureRoot = "feature"

        feature("login") {
            requiredLayer("presentation")
            requiredLayer("domain")
            requiredLayer("data")

            feature("chat") {
                requiredLayer("ui")
                requiredLayer("socket")
            }
        }

        forbid(
            "helper",
            "util",
            "manager"
        )
    }
}

Installation

1. Add ArchGuard to the app module or submodule of the project

your application or module build.gradle apply the plugin.

plugins {
    id("io.github.noncoderf.archguard.gradle") version "0.1.7"
}

2. Configure ArchGuard

archGuard {

    reports {
        html {
            enabled = true
            outputPath = "archguard-report.html"
        }
    }

    architecture {

        featureRoot = "feature"

        feature("login") {
            requiredLayer("presentation")
            requiredLayer("domain")
            requiredLayer("data")

            feature("chat") {
                requiredLayer("ui")
                requiredLayer("socket")
            }
        }

        forbid(
            "helper",
            "util",
            "manager"
        )
    }
}

3. (Optional) Create a shortcut task

Create an alias so you can run archGuardCheck instead of architectureCheck.

tasks.register("archGuardCheck") {
    group = "verification"
    description = "Runs the ArchGuard architecture validation."
    dependsOn("architectureCheck")
}

4. Run ArchGuard

./gradlew architectureCheck

or

./gradlew archGuardCheck

5. View the HTML Report

After the build completes successfully, ArchGuard generates an HTML report containing:

• ✅ Feature hierarchy
• ✅ Required layer validation
• ✅ Nested feature validation
• ✅ Forbidden folder detection
• ✅ Architecture violations
• ✅ Build summary

Open the generated report in your browser.

app/archguard-report.html

Philosophy

ArchGuard does not tell you how to architect your project.

Instead...

You define the architecture.

ArchGuard enforces it.

That means it works with

• Clean Architecture
• Modular Architecture
• Feature-first Architecture
• Layer-first Architecture
• DDD
• Your own conventions

Current Capabilities

Version 0.1

• Package structure validation
• Configurable architecture DSL
• Forbidden package detection
• Html reports

Planned Features

• Layer dependency validation
• Import analysis
• Circular dependency detection
• Architecture score
• HTML reports
• Dependency graph visualization
• GitHub Action
• IntelliJ Plugin
• SARIF support

Project Structure

ArchGuard

├── archguard-plugin
│
└── sample-project

Motivation

Senior engineers spend years learning architecture.

Junior engineers join the team with little context.

ArchGuard allows teams to encode architectural decisions into executable rules.

Instead of learning only from code reviews...

Developers receive immediate feedback during the build.

Roadmap

v0.1

✅ Package validation

✅ Gradle DSL

✅ HTML reports

v0.2

• Package declaration validation
• Dependency rules

v0.3

• Import analysis
• Layer dependency validation

v0.4

• Architecture score

v1.0

• Stable Rule Engine
• IntelliJ Plugin
• GitHub Action
• Html Reports

Why not Detekt?

Detekt focuses primarily on code quality and static analysis rules.

ArchGuard focuses on architectural integrity.

Examples:

• Does every feature contain the required layers?
• Does the project follow the team's architectural conventions?
• Are forbidden package structures introduced?
• (Future) Are layer dependencies respected?

The two tools complement each other rather than compete.

Contributing

Contributions are welcome.

If you'd like to improve ArchGuard:

1. Fork the repository.
2. Create a feature branch.
3. Open a pull request.

Please include tests for new functionality.

License

MIT License

⭐ If ArchGuard helps your team, consider giving the repository a star.

Architecture should be executable.

Not just documented.