Skip to content
nfr-review

Architecture Command

nfr-review arch scans one or more repositories and produces architecture documentation including technology maps, component diagrams, domain models, and optionally a Structurizr DSL workspace.

Usage

Section titled “Usage”
Terminal window
# Single repo — generates JSON + Markdown + PDF
nfr-review arch /path/to/repo


# Multiple repos as a unified report
nfr-review arch /path/to/repo1 /path/to/repo2


# Generate Structurizr DSL output
nfr-review arch --format dsl /path/to/repo


# Skip LLM-based analysis
nfr-review arch --no-llm /path/to/repo

Options

Section titled “Options”
Flag Default Description
--output-dir PATH reports Directory where report files are written
--format FORMAT json + md + pdf Output format(s): json, md, pdf, dsl. Repeat for multiple
--no-llm off Skip LLM-based analysis (domain model, market comparison)
--diagram-mode MODE hierarchical Component diagram layout: hierarchical or flat
--evidence-dir DIR — Directory containing evidence JSONL files (e.g. OTel traces)
-v / -q / --log-file — Verbosity controls, same as the run command

What it produces

Section titled “What it produces”

The arch command discovers components, integrations, and infrastructure from source code, manifests, and configuration files. It then generates:

  • Technology map — detected languages, frameworks, infrastructure, and CI/CD tools with file counts and locations
  • Domain model — extracted entity relationships and bounded contexts (LLM-enhanced when a backend is configured)
  • C4 diagrams — Mermaid architecture diagrams at context, container, component, and code levels
  • Risk assessment — architectural risks and recommendations
  • Multi-repo view — when given multiple repos, produces a cross-repo architecture overview

Output formats

Section titled “Output formats”

JSON

Section titled “JSON”

Structured ArchReport object with all components, integrations, diagrams, and metadata. Suitable for programmatic consumption.

Markdown

Section titled “Markdown”

Human-readable report with embedded Mermaid diagrams, technology tables, risk assessments, and recommendations.

PDF

Section titled “PDF”

Rendered version of the Markdown report via WeasyPrint. Requires the pdf extra: pip install "nfr-review[pdf]".

Structurizr DSL

Section titled “Structurizr DSL”

A C4 model workspace file that can be:

  • Rendered with Structurizr Lite
  • Exported to PNG/SVG via the Structurizr CLI
  • Version-controlled in Git to track architectural evolution
  • Diffed between scans to detect architectural drift
reports/arch-workspace.dsl
nfr-review arch --format dsl /path/to/repo
workspace "Architecture -- petclinic" "Auto-generated by nfr-review" {
    !identifiers hierarchical


    model {
        petclinic = softwareSystem "petclinic" "Primary system" {
            comp_petclinic = component "petclinic" "Root project" "Java, Spring Boot"
        }
        infra_postgresql = softwareSystem "Postgresql" "Infrastructure" {
            tags "External"
        }


        comp_petclinic -> infra_postgresql "JDBC connection" "jdbc:postgresql"
    }


    views {
        systemLandscape "landscape" {
            include *
            autoLayout tb
        }
        styles {
            element "External" {
                shape RoundedBox
                background #999999
                color #ffffff
            }
        }
    }
}

Component discovery

Section titled “Component discovery”

The arch command discovers components from multiple sources:

Source What it finds
Build files (pom.xml, build.gradle, pyproject.toml, go.mod) Project modules and their technologies
Docker Compose Service definitions and their relationships
Kubernetes manifests Deployments, services, and config maps
Helm charts Chart metadata and value schemas
OTel trace evidence Runtime service topology (when --evidence-dir is provided)

Integrations (database connections, API calls, message queues) are inferred from configuration files, connection strings, and dependency declarations.

Diagram modes

Section titled “Diagram modes”

The --diagram-mode flag controls component diagram layout:

  • hierarchical (default) — generates an overview diagram plus detailed diagrams for each major component. Better for large systems.
  • flat — single diagram showing all components. Better for smaller systems or quick overviews.

LLM dependency

Section titled “LLM dependency”

Without an LLM backend, arch produces technology maps, component analysis, and static C4 diagrams. With an LLM configured, it additionally generates:

  • Enhanced domain model with bounded context analysis
  • Market comparison showing how the architecture compares to common patterns

See Advanced Features for LLM setup.

Section titled “Related”