Repository Architecture Report Generator

[marco0560]

Issue: Repository Architecture Report Generator

Summary

Introduce a high-level repository architecture reporting system capable of generating architecture artifacts from a single command.

The report generator should produce:

• DOT dependency graphs
• SVG architecture diagrams
• Markdown architecture reports
• dependency statistics
• layer violation reports
• architectural hotspot reports

The goal is to provide a deterministic, repository-wide architectural view suitable for both humans and AI agents.

Motivation

Codira already possesses much of the information required to describe repository architecture:

• symbol references
• call relationships
• dependency relationships
• analyzer outputs
• repository statistics

Currently this information is exposed through individual commands.

Users must manually assemble a mental model of the repository.

A dedicated architecture report generator would transform repository intelligence into a consumable architectural artifact.

Potential use cases include:

• onboarding developers
• onboarding AI agents
• architecture reviews
• documentation generation
• dependency analysis
• technical debt identification
• repository health monitoring

Vision

A single command:

codira architecture-report

should generate a complete architecture package.

Example:

.codira/reports/
├── architecture.dot
├── architecture.svg
├── architecture.md
├── dependencies.json
├── hotspots.json
└── violations.json

Proposed CLI

Minimal Form

codira architecture-report

Explicit Output Directory

codira architecture-report --output docs/architecture

Optional Formats

codira architecture-report \
    --dot \
    --svg \
    --markdown

Generated Artifacts

DOT Graph

Generate Graphviz-compatible DOT output.

Purpose:

• graph analysis
• external rendering
• custom visualization workflows

Example:

package_a -> package_b
package_b -> package_c

SVG Architecture Diagram

Generate SVG diagrams directly through Graphviz when available.

Workflow:

Codira
  -> DOT
  -> Graphviz
  -> SVG

If Graphviz is unavailable:

• generate DOT only
• emit deterministic warning

SVG output should be considered a first-class feature.

Markdown Architecture Report

Generate a human-readable report containing:

• repository overview
• subsystem inventory
• dependency summary
• architectural observations
• hotspot summary
• layer violation summary

The report should be deterministic and machine-generated.

Dependency Statistics

Generate metrics such as:

Subsystem count
Dependency count
Average fan-in
Average fan-out
Maximum fan-in
Maximum fan-out
Strongly connected components
Cycles detected

Output:

dependencies.json

and corresponding Markdown tables.

Layer Violations

Identify architectural violations.

Examples:

Analyzer imports backend directly
Plugin imports internal implementation
UI depends on persistence layer

Initially support only explicitly configured rules.

Future analyzers may contribute additional checks.

Hotspot Analysis

Identify areas of elevated architectural importance.

Potential metrics:

• high fan-in
• high fan-out
• high coupling
• large dependency surface
• centrality measures

Output:

hotspots.json

and corresponding Markdown summaries.

Architecture Data Model

Introduce a repository architecture model:

RepositoryArchitecture
├── subsystems
├── dependencies
├── cycles
├── hotspots
├── violations
└── metrics

All renderers consume this common model.

This preserves deterministic behavior and allows future output formats.

Pluggable Architecture Providers

Architecture information should be extensible.

Potential providers:

Python analyzer
C analyzer
JSON analyzer
Future Rust analyzer
Future VHDL analyzer
Future TypeScript analyzer

Each provider contributes architecture facts to the common model.

This enables repository-wide reporting across mixed-language projects.

Phased Implementation

Phase 1

• Architecture domain model
• Dependency graph extraction
• DOT renderer

Phase 2

• Graphviz integration
• SVG generation
• Markdown report generation

Phase 3

• Dependency statistics
• Cycle detection
• Fan-in / fan-out analysis

Phase 4

• Layer violation framework
• Configurable architecture rules

Phase 5

• Hotspot analysis
• Centrality metrics
• Agent-oriented architecture summaries

Future Directions

Potential future outputs:

HTML report
PDF report
MkDocs integration
Architecture history tracking
Release-to-release architecture diffs

Potential future consumers:

Human developers
CI pipelines
Documentation systems
AI agents

Acceptance Criteria

• Single command generates all requested artifacts.
• DOT output is deterministic.
• SVG generation works when Graphviz is installed.
• Reports are reproducible.
• Output is analyzer-independent.
• Architecture model supports future language analyzers.
• Generated artifacts can be published directly in repository documentation.