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.