erode

Architecture erosion detection for GitHub PRs, GitLab MRs, Bitbucket PRs, and local changes using LikeC4 or Structurizr models and AI.

Compares pull request diffs or local git diffs against a LikeC4 or Structurizr architecture model to surface undeclared dependencies and structural changes. Works as a CLI tool and a GitHub Action. Use erode analyze for PR review and erode check for pre-push local detection. Supports GitHub pull requests, GitLab merge requests (experimental), and Bitbucket pull requests (experimental).

Supported AI providers: Gemini (default), OpenAI, and Anthropic (experimental).

New here? Start with Why it matters to understand the problem erode solves.

Why

Your architecture already exists in the code. Erode makes it visible during code review, showing not just the code diff but the architectural diff, so teams can have the conversation while the change is still small. A finding is not necessarily a problem. What matters is that the change is conscious and documented.

Read the full case for why this matters.

Quick start

Add erode to your GitHub Actions workflow:

name: Architecture Drift Review
on: [pull_request]

jobs:
  erode:
    runs-on: ubuntu-latest
    steps:
      - uses: erode-app/erode@0
        with:
          model-repo: 'org/architecture-model'
          ai-provider: gemini
          github-token: ${{ secrets.GITHUB_TOKEN }}
          gemini-api-key: ${{ secrets.GEMINI_API_KEY }}

See the GitHub Actions guide for inputs, outputs, and advanced examples.

Documentation

Full documentation at erode.dev.

Development

Requires Node.js >= 24.0.0.

npm install
npm run build          # Build core package (TypeScript + prompt templates)
npm run test           # Run all tests (vitest)
npm run lint           # ESLint (zero warnings allowed)
npm run format         # Prettier format (all packages)
npm run dev:web        # Start Astro dev server

Releasing

Release Please automates releases. It runs on every push to main, reads conventional commit messages, and maintains a release PR with the changelog.

Merge the release PR to create a GitHub release, tag, and Docker image.

Version bumps

The commit type determines the version bump:

To force a major bump, add ! after the commit type or include a BREAKING CHANGE: footer:

feat!: remove deprecated config options

BREAKING CHANGE: ERODE_MODEL_PATH no longer accepts relative paths.

Either the ! or the footer is enough on its own.

What counts toward a release

Only commits that touch packages/core/ or packages/cli/ trigger version bumps. Commits scoped to packages/web/, packages/architecture/, or packages/eslint-config/ are excluded and will not appear in the changelog.

License

Apache 2.0