architecture-analyzer

name	architecture-analyzer
description	Use this skill to analyze, map, or document a codebase's architecture. MANDATORY TRIGGERS: architecture, codebase structure, module map, layer diagram, dependency flow, how is this project organized, project structure analysis. Also use when: reviewing separation of concerns, identifying design patterns in use, generating architecture documentation, onboarding to an unfamiliar codebase. Do NOT use for: CI/CD pipeline review (use pipeline-auditor), infrastructure configs (use infra-config-analyzer), or individual API endpoint review (use api-contract-reviewer).
metadata	{"author":"N.V","version":"1.0"}
context	fork
agent	Explore
allowed-tools	Read, Grep, Glob, Bash

Overview

Analyzes a codebase's architecture by scanning directory structure, imports, module boundaries, and design patterns. Produces a structured architecture report with layer diagrams (Mermaid), module responsibility summaries, and identified patterns.

When to Use This Skill

• Understanding how an unfamiliar project is organized
• Documenting existing architecture for the team
• Identifying architectural anti-patterns (god modules, circular deps, leaky abstractions)
• Preparing for a refactoring or migration by mapping what exists today
• Generating an architecture overview for a README or ADR

Workflow

Quick Version (small project, < 20 files)

1. Glob the project tree, ignoring node_modules/, vendor/, .git/
2. Identify entry points (main, index, app)
3. Trace top-level imports to map layers
4. Output a brief architecture summary + Mermaid component diagram

Full Version (large project)

1. Scan structure — Glob full tree, categorize directories by role
2. Identify layers — find entry points, routers, controllers, services, models, utilities
3. Map dependencies — Grep for import/require/use statements across modules
4. Detect patterns — MVC, hexagonal, microservices, monolith, event-driven, etc.
5. Identify anti-patterns — circular imports, god modules, tight coupling
6. Generate report — structured markdown with Mermaid diagrams
7. Verify — cross-check that every top-level directory is accounted for

Analysis Checklist

□ Entry points identified (main/index/app/server)
□ Layer boundaries mapped (presentation → business → data)
□ Inter-module dependency directions documented
□ External integrations listed (databases, APIs, queues)
□ Design patterns named (MVC, repository, factory, etc.)
□ Anti-patterns flagged (if any)
□ Mermaid diagram generated

Critical Rules

• Read before judging — scan at least the top 3 levels of directories before drawing conclusions
• Name the patterns — always identify which architectural patterns are in use
• Flag, don't fix — this skill analyzes and reports; refactoring is a separate step
• Include unknowns — if a directory's purpose is unclear, say so explicitly
• NEVER modify any files — this is a read-only analysis skill

Output Format

# Architecture Report: [Project Name]

## Summary
[2-3 sentence overview of the architecture style]

## Layer Diagram
\`\`\`mermaid
graph TD
    A[Presentation Layer] --> B[Business Logic]
    B --> C[Data Access]
    C --> D[(Database)]
\`\`\`

## Module Breakdown
| Module/Directory | Responsibility | Depends On |
|-----------------|----------------|------------|
| src/api/        | REST endpoints | services   |
| src/services/   | Business logic | models     |
| src/models/     | Data schemas   | database   |

## Patterns Identified
- **[Pattern name]** — where and how it's applied

## Anti-Patterns / Risks
- **[Issue]** — impact and suggested action

## External Integrations
- [Database, API, queue, etc.]