ArchGuard (Architectural Drift Detector)

ArchGuard is a CLI tool designed to prevent "architectural drift" by verifying code changes against established Architectural Decision Records (ADRs). It is a semantic compliance engine that uses LLMs (via Ollama) to reason about whether your code changes violate the rules of specific ADRs.

🔍 See it in Action

ArchGuard sits between your code and your commit. When it detects code that violates your Architectural Decision Records (ADRs), it alerts you before the drift merges.

$ archguard check --staged
Analyzing internal/db/conn.js...
  Checking against ADR: Use Golang for Backend Services (0.92)

  [VIOLATION] Use Golang for Backend Services [Line 1]
  Reasoning: The file uses '.js' extension and contains JavaScript code, which violates the mandatory requirement to use Go for all backend logic.
  Code: const express = require('express');

⚡ Quick Start

1. Prerequisites

• Go 1.26+: Download Go
• Ollama: Download Ollama

2. Setup Models

Start Ollama and pull the required models:

ollama serve
# In a new terminal:
ollama pull llama3.2
ollama pull nomic-embed-text

3. Install

Quick Install

go install github.com/tgenz1213/archguard/cmd/archguard@latest

Build

git clone https://github.com/tgenz1213/archguard.git
cd archguard
go install ./cmd/archguard

4. Initialize & Run

Set up ArchGuard in your project:

archguard init

This interactive command will:

• Create archguard.yaml with defaults
• Set up the ADR directory (default: ./docs/arch)
• Optionally add an ADR template to get started
• Create .archguard/ for caching

Then index your ADRs and check for drift:

archguard index
archguard check --staged

---

🔒 Privacy & Data Flow

ArchGuard is designed with a "Local First" mentality.

• Local Analysis: When using the ollama provider, no code or documentation leaves your machine. All embeddings and analysis are performed locally.
• Cloud Analysis: When using openai, only the relevant code snippets and ADR text required for the specific audit are sent to OpenAI's API.

---

🛠️ Configuration

ArchGuard is configured via archguard.yaml in the root of your repository.

version: "1"

llm:
  provider: "ollama" # or "openai", "gemini"
  model: "llama3.2"
  base_url: "http://localhost:11434"
  max_tokens: 8000
  temperature: 0.0

vector_store:
  provider: "ollama"
  model: "nomic-embed-text"
  embedding_dim: 768
  similarity_threshold: 0.75
  connection_string: "" # e.g. postgres://user:pass@localhost:5432/archguard
  embedding_concurrency: 5

analysis:
  adr_path: "./docs/arch"
  accepted_statuses: ["Accepted", "Active"] # Use ["*"] to include all statuses
  exclude_patterns:
    - "**/*_test.go"
    - "vendor/**"
    - "go.sum"
    - "README.md"
  
  # Optional Confluence Integration
  confluence:
    enabled: false
    domain: "yourcompany.atlassian.net"
    space_id: "ARCH"
    username: "user@yourcompany.com"
    token: "ATATT3x..."
  max_concurrency: 5 # Number of files analyzed in parallel

Supported Statuses

You can filter ADRs by their status (e.g. ["Accepted"]). If you want ArchGuard to evaluate against all ADRs regardless of status, use ["*"].

Confluence Integration

ArchGuard can natively pull your ADRs from Atlassian Confluence using the Confluence REST API v2. To use it:

1. Enable confluence in your archguard.yaml.
2. Provide your Confluence domain (e.g. yourcompany.atlassian.net), the space_id where the ADRs live, your username, and an API token.
3. ArchGuard will crawl the specified space and evaluate your codebase against all pages matching your accepted_statuses.

ADR Format

ArchGuard parses ADRs from Markdown files. Strict YAML frontmatter is required.

Location: Store your ADRs in the folder specified by analysis.adr_path (default ./docs/arch).

---
title: "No Secrets in Logs"
status: "Accepted"
scope: "**/*.go" # Glob pattern matching file paths to apply this ADR to
---

## Context

Logging sensitive data is a security risk.

## Decision

Do not print passwords or secrets to console logs.

Frontmatter Fields:

• title (Required): Human friendly title.
• status (Required): Must match a value in analysis.accepted_statuses.
• scope (Optional): Glob pattern (e.g., src/**/*.ts). Supports standard Go globbing and recursive ** patterns.

Remote Vector Databases (pgvector)

By default, ArchGuard stores your ADR embeddings in a local .archguard/index.json file. For large teams or CI environments, you can centralize this index using PostgreSQL and the pgvector extension.

Simply provide a connection string in your archguard.yaml or set the ARCHGUARD_DB_URL environment variable:

export ARCHGUARD_DB_URL="postgresql://user:pass@host:5432/db"
archguard index

This will automatically create the archguard_adrs table and safely scope all ADRs by your repository's Project Name, preventing conflicts across different codebases sharing the same database. ArchGuard automatically manages an HNSW vector graph on this table and uses ON CONFLICT DO UPDATE queries to safely maintain the database state without locking table scans.

Note: If you're upgrading an existing PgStore install, run archguard index once after upgrading. A fix corrected how each ADR's ID and scope are stored in Postgres; existing rows only pick it up on their next index run, and until then archguard-ignore suppression, baseline scoping, and the scope glob filter may not work correctly for ADRs indexed before the upgrade.

---

📖 Usage Guide

CLI Commands

• archguard init: Interactive setup for local development. Creates config, ADR directory, and scaffolding.
• archguard index: Parses ADRs and generates vector embeddings. Run this whenever you add or edit an ADR.
  • Note: ArchGuard uses Delta Indexing, meaning it intelligently skips API calls for ADRs that haven't changed. Feel free to run it frequently!
• archguard check: Scans your codebase for violations.
  • (no arguments): Scans uncommitted changes (worktree).
  • <path>: Scans a specific file or directory.
  • --staged: Scan only staged (index) changes.
  • --all: Scan all tracked files.
  • --debug: Enable verbose logging.
  • --ci: Enable CI-safe mode.
  • --update-baseline: Scan the full repository (regardless of other flags/args) and overwrite archguard-baseline.json with every currently-detected violation.

Automation & Exit Codes

• 0: Success (no new violations found; baselined violations still exit 0).
• 1: General error (e.g. not run inside a git repository, baseline file I/O failure).
• 2: Usage error (missing/unknown command, bad flags).
• 3: Config error (failed to load or validate archguard.yaml).
• 4: Architectural drift detected.
• 5: Index error (failed to build, load, or fetch ADRs for the vector store).

Suppression

Intentionally ignore a violation for a specific file using a comment:

// archguard-ignore: 0001

• The ignore token must match the ADR ID (the numeric prefix of the filename).

Continuous Integration (CI)

You can run ArchGuard in your CI pipeline to prevent architectural drift from being merged into your main branch.

GitHub Actions

ArchGuard is available on the GitHub Marketplace. You can use our official composite action in your .github/workflows/ files:

name: ArchGuard Check
on: [push, pull_request]

jobs:
  archguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Run ArchGuard
        uses: Tgenz1213/ArchGuard@main
        with:
          provider: 'ollama'

This action automatically sets up Go, installs ArchGuard, and runs archguard check --ci on your codebase. If you set provider: 'ollama', it will also automatically install and configure Ollama with the required models.

Other CI Providers

If you are not using GitHub Actions, you can run ArchGuard manually by using the --ci flag in your pipeline.

Warn-Open Policy: Large files may be truncated to fit the LLM context. In --ci mode, truncated files result in a Warning rather than a failure, ensuring your pipeline doesn't break due to inconclusive analysis on massive files.

---

🔬 Technical Details

• Semantic Search: Uses cosine similarity to find relevant ADRs based on the code being analyzed.
• Index Optimizations: Employs Delta Indexing to bypass redundant LLM API calls on unchanged files, concurrent provider routines to mask network latency, and conditional HNSW graph maintenance routines in Postgres.
• Smart Truncation: Files exceeding the token limit are rolled back to the nearest newline character to preserve code integrity during analysis.
• Caching: Analysis results are persisted in .archguard/cache based on a hash of the model, ADR content, and file content to reduce API costs and execution time.
• Baseline Mode: Run archguard check --update-baseline to snapshot every currently-detected violation into archguard-baseline.json at the repository root. Subsequent archguard check runs load it automatically (no extra flag needed) and treat a matching violation as already-known — excluded from the new-violation count and exit code, but still reported separately (e.g. "3 new violations, 12 baselined"). An entry is invalidated, and its violation re-surfaces as new, once the specific code it originally cited is no longer present in the file. Unlike .archguard/index.json and .archguard/cache/, archguard-baseline.json is committed to git, so a team's grandfathered violations travel with the repository. Suppression is per (ADR, file) pair, so a second, different violation of an already-baselined ADR in the same file stays hidden until the originally-cited code changes — periodically re-running --update-baseline is recommended to catch these.
• Parallel Execution: Coordinates analysis across files using a worker pool (defaulting to 5 concurrent workers).

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for architectural overviews and technical standards.

📄 License

Distributed under the MIT License. See LICENSE for more information.