Code Architecture Inspection Across Repositories

Research Question

What practical implementation approaches exist for automatically inspecting and understanding how a set of repositories is architected, how they relate to and couple with each other, and whether they are following standards or drifting out of alignment — and which of these approaches can be operationalised using GitHub Copilot skills, agents, or adjacent tooling such as RepoSwarm?

Findings

(Populated from §6 Synthesis above.)

Executive Summary

[inference] The best-supported answer is that multi-repository architecture inspection should be implemented as a layered system in which deterministic tools extract structural and governance facts first, and a Large Language Model (LLM) layer produces the human-readable blueprint second. Sources: dependency-cruiser repository overview ; GitHub dependency graph Representational State Transfer (REST) API docs ; Open Policy Agent docs ; architecture-blueprint-generator skill

[inference] GitHub Copilot skills such as architecture-blueprint-generator and adjacent systems such as RepoSwarm are valuable because they package explanation, documentation, and workflow orchestration, but they are not strong enough on their own to serve as the primary truth source for coupling or standards drift. Sources: architecture-blueprint-generator skill ; RepoSwarm repository overview

[inference] The practical implementation seam is therefore extract -> normalize -> evaluate -> synthesize, with GitHub Actions running scanners and policy checks, versioned artifacts preserving provenance, and the synthesis layer turning those artifacts into reviewable architectural summaries. Sources: GitHub dependency graph Representational State Transfer (REST) API docs ; dependency-cruiser repository overview ; Open Policy Agent docs ; Prior completed research: agent evaluation cross-repo analysis ; Prior completed research: applied context engineering workflows

[inference] This matters because architecture understanding, standards enforcement, and cross-repository remediation require different mechanisms, and mixing them into one opaque agent step removes the provenance needed for drift analysis, trust, and repeatable governance. Sources: Prior completed research: dependency mapping ; Open Policy Agent docs ; OpenRewrite docs

Key Findings

1. [inference] [high confidence] A reliable multi-repository architecture inspection system should separate deterministic extraction from LLM-based synthesis, because reproducible graphs, manifests, and policy facts are required before any narrative blueprint can be trusted, compared across runs, or used for governance decisions. Sources: dependency-cruiser repository overview ; GitHub dependency graph Representational State Transfer (REST) API docs ; Open Policy Agent docs ; architecture-blueprint-generator skill
2. [fact] [high confidence] The architecture-blueprint-generator skill is a comprehensive architecture-documentation prompt covering technology detection, diagrams, layer rules, cross-cutting concerns, governance, and decision records, but it does not ship any native mechanism for cross-repository graph extraction or standards enforcement. Source: architecture-blueprint-generator skill
3. [inference] [medium confidence] RepoSwarm is the strongest open-source portfolio-analysis example in this evidence base because it performs multi-repository investigations, applies type-aware prompts, emits standardized .arch.md outputs, supports incremental updates, and keeps searchable results for later comparison. Source: RepoSwarm repository overview
4. [inference] [high confidence] dependency-cruiser, GitHub dependency graph and Software Bill of Materials (SBOM) exports, Renovate, and Sourcegraph each reveal a different structural layer — code imports, package manifests, dependency drift, and cross-repo search or bulk edits — so none of them alone is a complete architecture inspector. Sources: dependency-cruiser repository overview ; GitHub dependency graph Representational State Transfer (REST) API docs ; GitHub Software Bill of Materials (SBOM) REST API docs ; Renovate docs ; Sourcegraph docs index ; Sourcegraph Code Insights docs ; Sourcegraph Batch Changes docs
5. [inference] [high confidence] Standards alignment should be implemented as machine-checkable architecture fitness functions and policy rules over normalized facts, while architectural decision records (ADRs) remain the durable source for rationale and trade-off context that code graphs cannot express alone. Sources: Open Policy Agent docs ; ADR guidance site ; Neal Ford et al. — Building Evolutionary Architectures ; Building Evolutionary Architectures site
6. [inference] [medium confidence] OpenRewrite and Sourcegraph Batch Changes are better treated as remediation engines than as discovery systems, because they become valuable only after an earlier layer has already identified the drift pattern or forbidden dependency that must be corrected across repositories. Sources: OpenRewrite docs ; Sourcegraph Batch Changes docs
7. [fact] [high confidence] Prior repository research shows that any credible cross-repo architecture map must preserve provenance, freshness, semantic type, and confidence metadata on each edge, because declared structure, observed behavior, and documented intent are different kinds of truth rather than competing measurements of one truth. Source: Prior completed research: dependency mapping
8. [inference] [high confidence] In a GitHub-first operating model, the rollout that best matches this repository's constraints is to run repository scanners and normalizers in GitHub Actions, store the outputs as reviewable versioned artifacts, evaluate standards with policy-as-code, and then use a Copilot skill or RepoSwarm-style agent to generate the human-facing blueprint and remediation summary. Sources: GitHub dependency graph Representational State Transfer (REST) API docs ; dependency-cruiser repository overview ; Open Policy Agent docs ; architecture-blueprint-generator skill ; RepoSwarm repository overview

Assumptions

• [assumption] Public documentation is sufficiently current to support an implementation-plan recommendation. Justification: this item is scoped to public capability discovery, not private deployment verification. Sources: RepoSwarm repository overview ; architecture-blueprint-generator skill
• [assumption] The target repositories can tolerate small repository-local configuration files for scanners, policies, or generated outputs. Justification: every practical approach here requires at least one local configuration or artifact format. Sources: dependency-cruiser repository overview ; Open Policy Agent docs
• [assumption] RepoSwarm's repository overview is representative of its present practical behavior. Justification: no live RepoSwarm instance was deployed during this item. Source: RepoSwarm repository overview

Analysis

• [inference] The evidence supports a four-stage operating model: extract -> normalize -> evaluate -> synthesize. That structure is the smallest one that preserves provenance while still producing a usable architectural narrative. Sources: dependency-cruiser repository overview ; GitHub dependency graph Representational State Transfer (REST) API docs ; Open Policy Agent docs ; architecture-blueprint-generator skill
• [inference] Extraction should remain deterministic whenever possible, because architecture inspection loses organizational trust quickly when it cannot explain why an edge or violation was reported. Sources: dependency-cruiser repository overview ; Prior completed research: agent evaluation cross-repo analysis
• [inference] Synthesis is the natural place for Copilot skills and RepoSwarm-style agents, because they add clear value when translating structured evidence into diagrams, boundary explanations, onboarding context, and prioritized remediation advice. Sources: architecture-blueprint-generator skill ; RepoSwarm repository overview
• [inference] Remediation should remain separable from synthesis, because policy violations and dependency drift often need code changes that can be automated independently of the documentation pass. Sources: OpenRewrite docs ; Sourcegraph Batch Changes docs ; Open Policy Agent docs
• [inference] The core design decision is therefore not which single product wins, but where the repository draws the boundary between evidence production and interpretation. Sources: architecture-blueprint-generator skill ; RepoSwarm repository overview ; dependency-cruiser repository overview ; Open Policy Agent docs

Risks, Gaps, and Uncertainties

• [fact] The public evidence base is weaker on mature, language-agnostic open-source call-graph extraction across heterogeneous estates than it is on package, manifest, and repository-level metadata extraction. Sources: dependency-cruiser repository overview ; GitHub dependency graph Representational State Transfer (REST) API docs ; RepoSwarm repository overview
• [fact] RepoSwarm's repository overview is strong on end-to-end workflow shape, but weaker on the exact internal normalization model it uses before prompt generation. Source: RepoSwarm repository overview
• [fact] GitHub dependency-graph data is package-focused, so teams can misread package visibility as service-architecture visibility if they do not distinguish those semantics explicitly. Sources: GitHub dependency graph Representational State Transfer (REST) API docs ; GitHub Software Bill of Materials (SBOM) REST API docs
• [inference] A rollout that lets an agent inspect raw repository portfolios without first creating normalized evidence artifacts will likely become expensive, hard to review, and difficult to trust as repo count grows. Sources: Prior completed research: agent evaluation cross-repo analysis ; Prior completed research: dependency mapping ; RepoSwarm repository overview

Open Questions

• What is the thinnest normalized architecture schema that can represent imports, package dependencies, ownership, standards violations, ADR references, and generated blueprint links without becoming another heavyweight enterprise metamodel?
• Which open-source extractors outside the JavaScript and Java ecosystems are mature enough to provide equivalent structural evidence for Python, .NET, Go, and Infrastructure as Code (IaC) repositories?
• What is the minimum evaluation harness needed to measure false-positive and false-negative rates for cross-repository coupling detection before the system is trusted as a governance control?
• Should the synthesized output live primarily as per-repo architecture files, a central results hub, or both?

sources

• [x] architecture-blueprint-generator skill
• [x] awesome-copilot repository overview
• [x] RepoSwarm repository overview
• [x] dependency-cruiser repository overview
• [x] Sourcegraph docs index
• [x] Sourcegraph Code Insights docs
• [x] Sourcegraph Batch Changes docs
• [x] GitHub dependency graph Representational State Transfer (REST) API docs
• [x] GitHub dependency review REST API docs
• [x] GitHub Software Bill of Materials (SBOM) REST API docs
• [x] Renovate docs
• [x] OpenRewrite docs
• [x] Open Policy Agent docs
• [x] ADR guidance site
• [x] Neal Ford et al. — Building Evolutionary Architectures
• [x] Building Evolutionary Architectures site
• [x] Agent Skills standard site
• [x] Prior completed research: dependency mapping
• [x] Prior completed research: coding AI agent skills survey
• [x] Prior completed research: agent evaluation cross-repo analysis
• [x] Prior completed research: applied context engineering workflows