software-architecture-analysis

Software Architecture Analysis — Codebase Reverse Engineering to Design Document

When to Use

• A reference implementation exists and you need to understand its architecture for design inspiration
• You need a PRD, design document, or specification for a system in the same problem space
• The output must be clean-room: zero source code samples copied from the reference codebase
• You're designing a system with different architectural constraints (local-first, privacy-first, self-hosted) than the reference
• You need to extract an implicit contract — the storage operations a codebase performs — to design a formal provider abstraction

Don't use for: Direct code review, bug hunting, or security auditing (use a dedicated debugging skill instead). Simple tool or library evaluation (use a spike instead).

Build Workflow

Phase 1: Clone + Map  →  Phase 2: Find Key Files  →  Phase 3: Map Architecture
                                                              ↓
Phase 6: Constraint Redesign  ←  Phase 5: Write Spec  ←  Phase 4: Feature Inventory
                                                              ↓
                                                      Phase 7: QA

Phase 1: Repository Cloning and Structure Mapping

Clone the target repository with a shallow clone:

git clone --depth=1 https://github.com/owner/repo /tmp/target-repo

Map the top-level directory structure. For each directory, identify:

• What language/framework it uses
• Whether it's frontend, backend, service, firmware, or support
• Whether it's a core component (business logic) or support (CI, docs, tooling)

ls -la /tmp/target-repo/
find /tmp/target-repo -type f -name "*.swift" | sort   # or *.py, *.rs, *.ts, *.go

Phase 2: Identify Key Architectural Files

Sort by line count to find the heaviest files — these carry the core logic:

wc -l /tmp/target-repo/**/*.swift /tmp/target-repo/**/**/*.swift 2>/dev/null | sort -n

Read the top 15-25 files, prioritized in this order:

1. Entry points: main, App, bootstrap — how the app boots
2. Data models: types that flow through the system
3. Core services: capture, processing, storage pipelines
4. UI/page files: feature surface from the user's perspective
5. Configuration: env files, config structs — external dependencies
6. Privacy-sensitive files: any service accessing user data