architecture-scan

Infers a codebase's actual architecture from manifests, imports, and boundary contracts.

3|1|Updated Aug 26, 2026
One-click install
npx skills add https://github.com/zeljkoobrenovic/sokrates-skills --skill architecture-scan-zeljkoobrenovic
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: architecture-scan
Source: https://github.com/zeljkoobrenovic/sokrates-skills/tree/main/skills/scanners/architecture-scan
Command: npx skills add https://github.com/zeljkoobrenovic/sokrates-skills --skill architecture-scan-zeljkoobrenovic

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams often lack an accurate picture of how their codebase is actually structured: the documented architecture drifts from what the imports implement, dependency cycles and skip-layer violations accumulate unnoticed, and security boundaries go unmapped. This Skill reads the real structure and produces a verifiable architecture report. ## Core Features & Use Cases - Component and boundary mapping: Builds a directed component graph from workspace manifests, assigns each component a responsibility statement, and reads the contract artifacts (protocol crates, seam traits, event types) at load-bearing boundaries. - Deviation detection: Finds dependency cycles, skip-layer imports, grab-bag modules, duplicated concepts, and unjustified hubs, each stated relative to the intent the codebase itself implies. - Security boundary mapping: Records where untrusted data enters, sandbox and process-isolation mechanisms, network confinement, escape hatches, and open defaults as structural findings. - Use Case: Point it at a repository with a Sokrates _sokrates analysis to produce an onboarding-ready architecture report with validated findings rendered into an interactive HTML explorer. ## Quick Start Analyze this repository's architecture using the Sokrates analysis in the _sokrates folder and write the findings report.

Frequently Asked Questions about architecture-scan

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate an architecture overview of an existing codebase?

Run this scanner against a repository with a Sokrates _sokrates analysis. It builds a component graph from workspace manifests, reads entry points and boundary contracts, and writes a validated findings report rendered as an interactive HTML explorer.

How to detect dependency cycles and layering violations in a monorepo?

The scanner extracts the dependency graph from Cargo workspaces, package.json workspaces, or Bazel deps, then flags production cycles, skip-layer imports, and unjustified hubs. Test-only cycles from dev-dependencies are counted separately from production cycles.

Does architecture-scan require a Sokrates analysis to work?

It works best with a Sokrates _sokrates folder, using config.json's logicalDecompositions as a starting hypothesis and prior scan findings as the tech skeleton. The scan also judges where Sokrates' configured component split matches or misleads.

What is the difference between architecture-scan and security-scan?

architecture-scan maps security boundaries as structure: where untrusted data enters, sandbox mechanisms, and open defaults. Whether crossings are checked (auth, validation, injection) belongs to security-scan, which reads the architecture findings first.

Why does the scanner report few or no violation findings?

Violations are only reported relative to intent the codebase itself implies, such as documented layering or manifest structure. Clean architectures legitimately produce mostly info-level findings describing components, boundaries, and style.