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
• You need to assess architecture health, coupling, modularity, data ownership, distributed workflows, or readiness for a boundary change from repository evidence

Don't use for: Greenfield or proactive architecture design (route to software-architecture), direct code review, bug hunting, or security auditing. Route API/interface semantics to api-design-and-evolution, data-platform strategy to data-architect, implementation to the relevant engineering skill, deployment substrate to platform-engineering, and execution of an approved cross-system migration to migration-engineering.

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

Phase 3: Architecture Mapping

For each core service, identify:

• What it captures: data type, source, frequency, storage location
• Where it processes: local vs cloud, which APIs/services are called
• Where it stores: local database, cloud database, file system
• External dependencies: every third-party service, API key, cloud provider
• Privacy profile: what data leaves the machine, under what conditions

Build diagrams using Mermaid syntax (renders natively in GitHub and most markdown editors):

graph TD
    subgraph Capture["Capture Layer"]
        CAM[Camera/Mic Capture]
        FS[File Scanner]
    end

    subgraph Processing["Processing Layer"]
        OCR[OCR/NLP]
        STT[Speech-to-Text]
    end

    subgraph Storage["Storage Layer"]
        DB[(Local Database)]
        CLOUD[(Cloud Sync)]
    end

    CAM --> OCR
    FS --> OCR
    STT --> DB
    OCR --> DB
    DB --> CLOUD

    style Capture fill:#0a1a2e,stroke:#22d3ee
    style Processing fill:#0a2a1a,stroke:#34d399
    style Storage fill:#1a0a3a,stroke:#a78bfa

Use subgraphs for cloud/local boundaries. All diagram code blocks MUST use ```mermaid — never ASCII box drawing, never image files.

Architecture evidence lenses

After the initial map, load only the references needed by the question:

• Architecture characteristics analysis when inferring quality characteristics from observed scenarios, controls, and operational evidence.
• Coupling, modularity, and decomposition when comparing boundaries, change propagation, modularity, deployment shape, or decomposition readiness. Assess static, dynamic, data, temporal, deployment, and organizational coupling before naming a target boundary.
• Data ownership and workflow analysis when tracing data authority, distributed transactions, orchestration/choreography, failure handling, or reconciliation.
• Architecture health assessment template when the deliverable is a repeatable health report or a structured handoff.

Treat every claim as observed, inferred, reported, or unknown. Cite the artifact, trace, configuration, test, metric, or interview evidence that supports it. Do not turn a missing observation into a defect without labeling the uncertainty.

Phase 3b: Interface Extraction Pattern (DAO/Provider Contract Design)

When the goal is to extract an implicit contract — what operations does this codebase need from its database or storage layer? — follow this variant:

Step 1 — Read the philosophy first

Before touching code, read any PHILOSOPHY.md, DESIGN.md, ARCHITECTURE.md, or main README. These contain the design constraints the interface must respect. For example, the cashew thought-graph library's PHILOSOPHY.md says "dumb graph, smart reasoning layer" — edges carry no type labels, node types are descriptive hints for the LLM, not load-bearing for graph engine operations. That constraint must be baked into the contract.

Step 2 — Catalog every storage operation

Read every file that touches the storage layer (database, filesystem, external service). For each file, list every distinct operation:

Target files by naming convention: db.py, store.py, storage.py, embedding.py, session.py, persist.py, and any batch/maintenance modules.

Step 3 — Identify workarounds that signal boundary leaks

The code that exists because of substrate limitations rather than application logic. Signals:

• Dual-write patterns (same data to two tables for different query paths)
• Dimension-mismatch detection and fallback chains
• Full-table loads into numpy/scipy for operations a native substrate would support
• Recursive CTEs that reimplement graph traversal in SQL
• try/except switching between fast and fallback paths
• Comments like "needed because X doesn't support Y natively"

These workarounds are the cost of the current boundary being in the wrong place. They are candidates to move behind the contract.

Step 4 — Design the contract from the catalog

Define the abstract interface (ABC, Protocol, or trait) capturing every operation from Step 2 without leaking substrate-specific details from Step 3.

Design principles:

• Design against what the codebase needs, not what the current substrate does
• Let the philosophy constrain the interface
• The expensive operations (similarity search, graph traversal, scanning) define the performance profile — the contract must make them implementable efficiently on a native substrate
• Transactions must be explicit

Step 5 — Validate with a two-provider proof

Design a second provider implementation to test the abstraction. It doesn't need to be production-ready — it just needs to pass the same test suite. The two-provider proof catches:

• Operations too specific to the original substrate's semantics
• Missing operations the second provider would need
• Contract leaks (method signatures that assume SQL-like cursor behavior instead of returning data classes)

See references/interface-extraction-pattern.md for a full worked example using the cashew thought-graph library — a real open-source project demonstrating all five steps.