ADRScope

A lightweight visualization tool for Architecture Decision Records (ADRs).

ADRScope generates self-contained HTML viewers for ADRs following the structured-MADR format. It supports faceted search, relationship graphs, and GitHub Wiki generation.

GitHub Action

Use ADRScope in your CI/CD pipelines to validate ADRs and generate documentation automatically.

- name: Validate ADRs
  uses: zircote/adrscope@v0
  with:
    command: validate
    input-dir: docs/decisions
    strict: true

Action Features

• All commands available: validate, generate, stats, wiki
• Inline annotations: Validation errors appear directly in PR diffs
• Cross-platform: Linux, macOS, Windows (x86_64, ARM64)
• Fast startup: Pre-built binaries (~2-5 seconds)

Example Workflow

name: ADR CI
on:
  pull_request:
    paths: ['docs/decisions/**']

jobs:
  adr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate ADRs
        uses: zircote/adrscope@v0
        with:
          command: validate
          strict: true

      - name: Generate Viewer
        uses: zircote/adrscope@v0
        with:
          command: generate
          output: adr-viewer.html

      - uses: actions/upload-artifact@v4
        with:
          name: adr-viewer
          path: adr-viewer.html

Publishing to GitHub Wiki

ADRScope can generate wiki pages and automatically publish them to your repository's GitHub Wiki.

Generated Wiki Pages:

• ADR-Index.md - Main index with table of all ADRs
• ADR-By-Status.md - ADRs grouped by status (proposed, accepted, deprecated, superseded)
• ADR-By-Category.md - ADRs grouped by category
• ADR-Timeline.md - Chronological timeline view
• ADR-Statistics.md - Summary statistics and breakdowns

Complete Wiki Deployment Workflow:

name: Deploy ADRs to Wiki

on:
  push:
    branches: [main]
    paths:
      - 'docs/decisions/**'

jobs:
  deploy-wiki:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4

      - name: Generate Wiki Pages
        uses: zircote/adrscope@v0
        with:
          command: wiki
          input-dir: docs/decisions
          output: wiki/

      - name: Deploy to Wiki
        uses: Andrew-Chen-Wang/github-wiki-action@v4
        with:
          path: wiki/

With Validation:

Validate ADRs before deploying to wiki:

name: Deploy ADRs to Wiki

on:
  push:
    branches: [main]
    paths:
      - 'docs/decisions/**'

jobs:
  deploy-wiki:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4

      - name: Validate ADRs
        uses: zircote/adrscope@v0
        with:
          command: validate
          strict: true

      - name: Generate Wiki Pages
        uses: zircote/adrscope@v0
        with:
          command: wiki
          output: wiki/

      - name: Deploy to Wiki
        uses: Andrew-Chen-Wang/github-wiki-action@v4
        with:
          path: wiki/

Wiki Command Options:

📖 Full Action Documentation →

Screenshots

Main Viewer

ADR Details with Relationship Graph

ADR Content View	Category Breakdown

Faceted Search & Filtering

Filter Panel	Filtered Results

Features

• Self-contained HTML viewer - Single file with embedded CSS/JS, no dependencies
• Faceted search - Filter by status, category, tags, author, project, and technologies
• Relationship graphs - Interactive visualization of ADR relationships
• Multiple themes - Light, dark, and system-preference modes
• GitHub Wiki generation - Generate wiki pages with index, status, category, and timeline views
• Validation - Check ADRs for required and recommended fields
• Statistics - Analyze your ADR collection with detailed breakdowns
• Lenient parsing - Gracefully handles non-standard status values with warnings

Installation

GitHub Action (Recommended for CI/CD)

- uses: zircote/adrscope@v0
  with:
    command: validate

See ACTION.md for full documentation.

Homebrew (macOS/Linux)

brew install zircote/tap/adrscope

From crates.io

cargo install adrscope

From source

git clone https://github.com/zircote/adrscope.git
cd adrscope
make install

Quick Start

# Generate an HTML viewer from ADRs in docs/decisions
adrscope generate -i docs/decisions -o adr-viewer.html

# Validate ADRs (useful for CI/CD)
adrscope validate -i docs/decisions --strict

# Show statistics
adrscope stats -i docs/decisions

# Generate GitHub Wiki pages
adrscope wiki -i docs/decisions -o wiki/

Documentation

• GitHub Action Documentation
• Getting Started Guide
• User Guide
• Configuration Reference
• Library API Guide - Using ADRScope as a Rust library
• Troubleshooting - Common issues and solutions
• Contributing Guide - Development workflow and conventions
• Architecture Decision Records

Commands

Generate Options

adrscope generate [OPTIONS]

Options:
  -i, --input <DIR>     Input directory [default: docs/decisions]
  -o, --output <FILE>   Output HTML file [default: adrs.html]
  -p, --pattern <GLOB>  File pattern [default: **/*.md]
  -t, --title <TITLE>   Page title [default: "Architecture Decision Records"]
      --theme <THEME>   Theme: light, dark, auto [default: auto]
  -v, --verbose         Enable verbose output

Validate Options

adrscope validate [OPTIONS]

Options:
  -i, --input <DIR>     Input directory [default: docs/decisions]
  -p, --pattern <GLOB>  File pattern [default: **/*.md]
  --strict              Fail on warnings (for CI/CD)
  --json                Output as JSON
  -v, --verbose         Enable verbose output

ADR Format

ADRScope expects ADRs in the zircote/structured-madr format:

---
title: Use PostgreSQL for Data Storage
description: Decision to use PostgreSQL as our primary database
status: accepted
category: architecture
tags:
  - database
  - postgresql
created: 2025-01-15
author: Architecture Team
related:
  - adr-0001.md
  - adr-0003.md
---

## Context

[Describe the context and problem...]

## Decision

[Describe the decision...]

## Consequences

[Describe the consequences...]

Supported Status Values

Unknown status values are handled gracefully with a warning.

Library Usage

use adrscope::application::{GenerateOptions, GenerateUseCase};
use adrscope::infrastructure::fs::RealFileSystem;

let fs = RealFileSystem::new();
let use_case = GenerateUseCase::new(fs);
let options = GenerateOptions::new("docs/decisions")
    .with_output("adr-viewer.html");

let result = use_case.execute(&options)?;
println!("Generated viewer with {} ADRs", result.adr_count);

Development

Prerequisites

• Rust 1.85+ (2024 edition)
• cargo-deny for supply chain security

Build Commands

make build      # Build debug binary
make release    # Build optimized binary
make test       # Run all tests
make lint       # Run clippy linter
make fmt        # Format code
make check      # Quick check (fmt + lint + test)
make ci         # Full CI pipeline
make install    # Install to ~/.cargo/bin

Code Quality

• Linting: clippy with pedantic and nursery lints
• Safety: #![forbid(unsafe_code)]
• Testing: 170+ tests with 95%+ coverage
• Supply Chain: cargo-deny for dependency auditing

MSRV Policy

The Minimum Supported Rust Version (MSRV) is 1.85. Increasing the MSRV is considered a minor breaking change.

Contributing

Contributions are welcome! See CONTRIBUTING.md for:

• Development setup and workflow
• Code conventions and architecture guidelines
• Testing requirements
• Pull request process

Quick start for contributors:

git clone https://github.com/zircote/adrscope.git
cd adrscope
make check  # Run fmt + lint + test

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• MADR - Markdown ADR format
• ADR GitHub Organization - ADR resources and tools