Module 3: Understand an Existing Architecture

Module Project: Architecture Map of a Real Project

Next →

Module Project: Architecture Map of a Real Project

Project description

This is the project that closes Phase 1 of the guide. You're going to produce a complete Architecture Map of a real project — a document that combines dependency maps (capsule 02), flow analysis (capsule 03), and pattern/anti-pattern identification (capsule 04) into a professional artifact any developer can consult.

This project carries special weight because its output is the direct input for Module 4 (Coordinated Multi-File Refactoring). The Architecture Map you produce here informs what to refactor, in what order, and with what risks. Without this map, refactoring is a gamble; with it, it's an informed decision.

The scenario is realistic: your team needs to plan the next quarter of technical improvements. To do it, they need an architectural analysis of the main codebase. You produce that analysis using Claude Code. The deliverable isn't an academic exercise — it's a working document that informs engineering decisions.

The difference from the Module 1 project (onboarding) and the Module 2 project (exploration) is the level of formality and completeness. Here you don't just explore and document findings — you produce an analysis package with three structured components, actionable conclusions, and a prioritized improvement plan.

Project Objective

Generate a complete Architecture Map of a real project using Claude Code, integrating dependency analysis, flow analysis, and pattern identification into a professional reference document.

By completing this project:

  • ✅ You'll have generated dependency maps at multiple zoom levels
  • ✅ You'll have traced at least 2 critical flows in the project
  • ✅ You'll have identified patterns and anti-patterns with prioritization
  • ✅ You'll have produced a reference document for the team
  • ✅ You'll have connected findings with actionable refactoring decisions

Technical Specifications

Codebase to Analyze

Option A — Suggested project (recommended for learning):

Use the same project you explored in Modules 1-2 (httpx, typer, rich, or fastapi). This lets you dig deeper into a codebase you already know superficially.

Option B — Your own project:

If you work on a real project that needs architecture analysis, use it. The benefit is that you produce an artifact useful for your team.

Minimum codebase requirements:

  • At least 5K lines of code
  • At least 3 main directories/modules
  • At least 1 significant external dependency
  • Some degree of architectural complexity (not a single file)

Tools

  • Claude Code with the Explore subagent
  • Terminal for complementary grep
  • Text editor for the final document
  • Optional: Mermaid Live Editor to visualize diagrams

Setup

# If you use a new project:
git clone [PROJECT_URL]
cd [project_name]
claude

# If you continue with the Module 1-2 project:
cd [project_name]
claude

The 3 Components of the Architecture Map

Component 1: Dependency Analysis

What you must produce:

  1. High-level dependency map — A diagram showing the 4-6 main components and how they connect
  2. Dependency map of a critical module — A detailed diagram of a module with outgoing and incoming dependencies
  3. External dependencies table — Each external library/package, what's used, and where

Deliverable format:

### 1. Dependency Analysis

#### 1.1 High-Level Dependency Map

[Mermaid or ASCII diagram]

**Description:** [1-2 paragraphs describing the structure]

#### 1.2 Detailed: [Critical module]

Outgoing dependencies:
| Module | What it imports | What for |
|--------|-------------|----------|
| ... | ... | ... |

Incoming dependents:
| Module | What it uses | Risk if it changes |
|--------|---------|------------------|
| ... | ... | ... |

[Mermaid diagram of the module]

#### 1.3 External Dependencies

| Package | Version | Main use | Files that use it |
|---------|---------|---------------|---------------------|
| ... | ... | ... | ... |

#### 1.4 Dependency Findings

- [Finding 1: e.g., "Circular dependency between X and Y"]
- [Finding 2: e.g., "Module Z has a fan-out of 12"]
- [Finding 3: e.g., "Dependency A is deprecated"]

Suggested prompts:

> "Generate a high-level dependency map of the project.
   Show the 5-6 main components and the
   dependencies between them. Mermaid format."

> "Analyze the dependencies of [critical module].
   List outgoing and incoming dependencies in detail."

> "List all the project's external dependencies
   with version, main use, and files that use them."

> "Are there circular dependencies, modules with excess
   dependencies, or deprecated dependencies?"

Component 2: Flow Analysis

What you must produce:

  1. Main flow — A complete trace of the project's most important flow (the happy path of the main feature)
  2. Secondary flow — A trace of a second significant flow (it can be error handling, an async flow, or a background job)
  3. Data transformation — How the data is transformed in at least one of the flows

Deliverable format:

### 2. Flow Analysis

#### 2.1 Main Flow: [Flow name]

**Trigger:** [What starts the flow]
**Result:** [What it produces]

| Step | File | Function | Input | Output |
|------|---------|---------|-------|--------|
| 1 | ... | ... | ... | ... |
| 2 | ... | ... | ... | ... |
| ... | ... | ... | ... | ... |

[Mermaid sequence diagram]

**Side effects:** [List of everything that happens besides the main result]

**Error handling:** [How errors are handled at each critical step]

#### 2.2 Secondary Flow: [Name]

[Same structure]

#### 2.3 Data Transformation: [Flow name]

| Step | Data structure |
|------|-------------------|
| Input | `{field1: type, field2: type}` |
| After validation | `{...validated fields...}` |
| After processing | `{...enriched fields...}` |
| What's saved in the DB | `{...DB model...}` |
| Response to the client | `{...response fields...}` |

#### 2.4 Flow Findings

- [Finding 1: e.g., "The checkout flow has no rollback if the email fails"]
- [Finding 2: e.g., "There are 3 undocumented side effects in order creation"]

Suggested prompts:

> "Trace the complete flow of [main feature].
   For each step: file, function, input, output."

> "Generate a mermaid sequence diagram for [flow]."

> "Trace how the data is transformed in [flow]
   from the input to what's saved in the DB."

> "Are there points in [flow] where an error could leave
   inconsistent data?"

Component 3: Pattern & Anti-Pattern Analysis

What you must produce:

  1. Identified patterns — What architectural patterns the project uses
  2. Anti-patterns found — A prioritized list of anti-patterns with severity
  3. Improvement plan — Top 5 prioritized refactoring actions

Deliverable format:

### 3. Pattern & Anti-Pattern Analysis

#### 3.1 Architectural Patterns

| Pattern | Where | Consistency | Notes |
|---------|-------|-------------|-------|
| [e.g., Service Layer] | src/services/ | High | Thin controllers, services with logic |
| [e.g., Repository] | src/repos/ | Medium | Only for User and Order, not for Product |
| ... | ... | ... | ... |

#### 3.2 Anti-Patterns Found

| # | Anti-Pattern | File | Severity | Impact |
|---|-------------|---------|-----------|---------|
| 1 | [e.g., God Object] | [path] | High | [description] |
| 2 | [e.g., Circular Dep] | [paths] | Medium | [description] |
| ... | ... | ... | ... | ... |

#### 3.3 Prioritized Improvement Plan

| Priority | Action | Anti-Pattern | Risk | Impact |
|-----------|--------|-------------|--------|---------|
| 1 | [e.g., Remove dead code] | Dead Code | Low | Medium |
| 2 | [e.g., Split UserManager] | God Object | High | High |
| 3 | [e.g., Resolve circular dep auth↔user] | Circular | Medium | High |
| 4 | ... | ... | ... | ... |
| 5 | ... | ... | ... | ... |

Structure of the Final Deliverable

# Architecture Map: [Project Name]

**Analyst:** [Your name]
**Date:** [Date]
**Codebase:** [URL or description]
**Tools:** Claude Code + Explore subagent

## Executive Summary

[3-5 sentences: what the project is, what its architectural state is,
and the 2-3 most important conclusions]

---

## 1. Dependency Analysis
[Complete Component 1]

---

## 2. Flow Analysis
[Complete Component 2]

---

## 3. Pattern & Anti-Pattern Analysis
[Complete Component 3]

---

## 4. Conclusions and Recommendations

### Architectural strengths
- [What's well designed]
- [Patterns that work]

### Areas for improvement
- [Top 3 anti-patterns to resolve]

### Recommended action plan
1. [Immediate action (low risk)]
2. [Short-term action]
3. [Medium-term action]

---

## 5. Metrics

| Metric | Value |
|---------|-------|
| Total analysis time | [X minutes/hours] |
| Prompts to Claude Code | [X] |
| Files analyzed | [X] |
| Anti-patterns found | [X] |
| External dependencies | [X] |

---

## Appendix: Prompts Used

[List of all the exact prompts used, for reproducibility]

Success Criteria

Your project is complete when:

  • ✅ High-level dependency map with a diagram included
  • ✅ Detailed dependency map of at least 1 module
  • ✅ At least 2 flows traced with detailed steps
  • ✅ At least 1 data transformation documented
  • ✅ Architectural patterns identified and named
  • ✅ At least 3 anti-patterns found with severity
  • ✅ Prioritized improvement plan with 5 actions
  • ✅ Executive summary concise and actionable
  • ✅ Prompts documented for reproducibility
  • ✅ The document is readable by any developer on the team

Evaluation Rubric (100 points)

Dependency Analysis (30 points)

  • (10 pts) Complete high-level dependency map with a diagram
  • (10 pts) Detailed analysis of 1+ module with outgoing/incoming
  • (5 pts) External dependencies table
  • (5 pts) Dependency findings documented

Flow Analysis (30 points)

  • (10 pts) Main flow traced step by step with a diagram
  • (10 pts) Secondary flow traced
  • (5 pts) Data transformation documented
  • (5 pts) Flow findings (errors, side effects, inconsistencies)

Pattern Analysis (25 points)

  • (8 pts) Architectural patterns identified correctly
  • (8 pts) Anti-patterns found with assigned severity
  • (9 pts) Prioritized improvement plan (5 actions with impact/risk)

Documentation and Professionalism (15 points)

  • (5 pts) Clear and actionable executive summary
  • (5 pts) Prompts documented (reproducibility)
  • (3 pts) Complete time metrics
  • (2 pts) Clean, readable, professional format

Extra Credit (up to +10 points)

  • (+3 pts) Rendered mermaid diagrams (not just code)
  • (+3 pts) Comparison with the project's existing documentation
  • (+2 pts) 3+ flows traced (instead of the minimum of 2)
  • (+2 pts) Recommendations include effort estimation

Minimal Implementation Example

This is an abbreviated example of the Executive Summary and Component 1 for the httpx project:

# Architecture Map: httpx

**Analyst:** [Name]
**Date:** April 2026
**Codebase:** https://github.com/encode/httpx

## Executive Summary

httpx is a Python HTTP client with sync and async support. The architecture
follows a clean layers pattern: public API (convenience functions) →
Client (session management) → Transport (HTTP connection) → httpcore
(protocol). The main strength is the separation of concerns between
layers. The main areas for improvement are: coupling between Client
and Transport, and a lack of consistent abstraction for HTTP/1.1 vs HTTP/2.

## 1. Dependency Analysis

### 1.1 High-Level Dependency Map

```mermaid
graph TD
    API[_api.py - Convenience] --> Client[_client.py - Session]
    Client --> Transport[_transports/ - Connection]
    Client --> Models[_models.py - Request/Response]
    Client --> Auth[_auth.py - Authentication]
    Transport --> httpcore[httpcore - Protocol]
    Models --> URLLib[_urls.py - URL handling]

Description: httpx has 4 main layers. The API layer is a thin wrapper over Client. Client handles sessions, auth, and redirects. Transport handles the real HTTP connection by delegating to httpcore. Models defines Request and Response as immutable objects.

[... continues with the rest of the analysis ...]


---

## Common Errors

### Error 1: An Architecture Map that's too superficial

**Example:** A dependency map of 3 boxes with no details. Flows of 2 steps.
**Solution:** Go deeper. The high-level map has 4-6 components. The detailed one has 8+ dependencies. The flows have 5+ steps.

### Error 2: Anti-patterns without prioritization

**Example:** A list of 10 anti-patterns without severity or an action plan.
**Solution:** Every list needs prioritization. Use the impact/risk matrix.

### Error 3: Not including prompts

**Example:** A complete analysis but without documenting how it was generated.
**Solution:** The prompts are part of the deliverable. They enable reproducibility and teach others to do the same.

### Error 4: Copying Claude Code's output without interpreting

**Example:** "Claude Code reported: [raw output]"
**Solution:** Claude Code generates data. You produce analysis. Interpret, connect the dots, draw conclusions.

### Error 5: Ignoring inconsistencies

**Example:** The dependency map shows that A doesn't depend on B, but the flow trace shows that A calls B.
**Solution:** Investigate and resolve. An inconsistency between the dependency map and the flow trace can indicate a hidden dependency (via events, globals, or reflection).

### Error 6: A generic improvement plan

**Example:** "Improve the architecture and reduce tech debt."
**Solution:** Specific actions: "Split UserManager into UserAuthService and UserProfileService" with concrete files.

### Error 7: Not connecting with refactoring

**Example:** An Architecture Map without an action plan.
**Solution:** Component 3 must end with 5 prioritized actions that are directly executable in Module 4.

### Error 8: Choosing a project without complexity

**Example:** Analyzing a 200-line project with 1 file.
**Solution:** A minimum of 5K lines, 3+ modules. If there's no complexity, there's nothing to analyze.

---

## Resources for the Project

1. [Mermaid Live Editor](https://mermaid.live/) - To visualize and refine mermaid diagrams
2. [Architecture Decision Records](https://adr.github.io/) - A standard format for documenting architectural decisions
3. [C4 Model](https://c4model.com/) - An architecture diagramming framework by zoom levels
4. [httpx - GitHub](https://github.com/encode/httpx) - A suggested project for analysis
5. [pydeps](https://pypi.org/project/pydeps/) - A dependency graph generator for Python
6. [Architecture Review Checklist](https://wiki.sei.cmu.edu/confluence/display/ARID) - The SEI/CMU architectural review checklist

---

## Connection with the Next Module

This Architecture Map is the close of **Phase 1: Understand Codebases**. Everything that follows in Phase 2 is built on this foundation.

**Module 4: Coordinated Multi-File Refactoring** takes your prioritized improvement plan and executes it. The transition is direct:

- The **anti-patterns** you found are the refactoring targets
- The **dependency maps** show you which files will be affected by each change
- The **flow traces** confirm that the behavior is preserved after the refactoring
- The **improvement plan** is your work backlog

"Now you have the complete map of the codebase: structure, dependencies, flows, patterns. It's time to improve what you found. The first type of improvement is refactoring — changing the structure of the code without changing its behavior. And with Claude Code, you can coordinate refactoring that touches 5, 10, or 20 files at once."
← PreviousPattern Identification and Anti-Pattern DetectionNext →Module 4: Coordinated Multi-File Refactoring