Module 3: Understand an Existing Architecture

Capsule description

You're going to learn to transform exploration into documented architectural comprehension. In the previous modules you learned to explore a codebase (Module 1) and to investigate in depth with specialized tools (Module 2). But exploring and understanding aren't the same thing. You can navigate a codebase file by file, read every function, follow every import — and still not understand the architecture. Not understand how the pieces fit together, what depends on what, how the data flows end-to-end, what patterns repeat and which are accidental.

This module closes that gap. It's the highest level of comprehension before modifying code. When you finish, you won't just "know" the codebase — you'll have a complete map: dependency maps that show which module depends on which, flow diagrams that trace requests from the entry point to the response, and pattern analysis that identifies both what works well and what needs improvement. All generated with Claude Code.

The difference between a developer who "explored" a codebase and one who "understands its architecture" is the difference between having visited a city and having a map of the city. The tourist knows where some places are. The cartographer can plan routes, identify bottlenecks, and decide where to build. This module makes you a cartographer.

Module Context

Where are we?

This is Guide #8 of the Claude Code Agentic Development Path — "Refactoring & Legacy Code with Claude Code." You're in Module 3 of 8, the last module of Phase 1: Understand Codebases.

What you built in the previous modules:

Module	What you learned	The level of comprehension you achieved
Module 1: Onboarding with AI	The systematic method of the 5 questions, exploration with Claude Code, documenting findings	Familiarity: "I know what this project does, where things are, and how the data flows at a high level"
Module 2: Agentic Research with Explore	Explore subagent, semantic search, advanced exploration patterns	Precise access: "I can find anything in the codebase and trace features end-to-end"

Module 3 adds the final layer:

Module 3: Understand Architecture	Dependency maps, flow analysis, pattern identification, anti-pattern detection	Complete map: "I can visualize and explain the architecture to anyone"

The progression of Phase 1 is intentional:

Module 1: Familiarity
   "I know the codebase"
        |
        v
Module 2: Precise access
   "I can find anything"
        |
        v
Module 3: Complete map              <-- YOU ARE HERE
   "I can visualize and explain the architecture"

Each module gives you a deeper level of comprehension. Module 1 gave you the "what." Module 2 gave you the "where." Module 3 gives you the "how" — how the pieces connect, how the data flows, how the patterns are organized.

Where are we headed?

This module closes Phase 1 and directly prepares for Phase 2:

Phase 1: Understand Codebases (Modules 1-3)
+-- Module 1: Onboarding with AI                    ✅ Completed
+-- Module 2: Agentic Research with Explore          ✅ Completed
+-- Module 3: Understand an Existing Architecture     <-- YOU ARE HERE

Phase 2: Refactoring (Modules 4-6)
+-- Module 4: Coordinated Multi-File Refactoring
+-- Module 5: Framework and Language Migration
+-- Module 6: Context Management for Large Projects

Phase 3: Legacy and Project (Modules 7-8)
+-- Module 7: Modernize Legacy Code
+-- Module 8: Capstone Project — Full Migration

The transition from Phase 1 to Phase 2 is the most important moment of the guide. Up to now you've invested all the effort in comprehension — deliberately. You haven't modified code significantly. That changes in Module 4.

But you don't change blindly. You change with a map. The architecture map you produce in this module is the direct input for Module 4. When you need to decide what to refactor, the map tells you where the problematic dependencies are. When you need to coordinate a multi-file refactoring, the map tells you which files affect each other. When you need to prioritize, the map tells you which anti-patterns have the greatest impact.

Without a map, every refactoring is a gamble. With a map, it's a calculated decision.

Why does this module matter?

The gap between exploring and understanding

Imagine you explored a codebase with the Module 1 method. You know there's a services/ directory with 12 files, a models/ directory with 8, and an api/ directory with 15 endpoints. You know it uses SQLAlchemy, has authentication middleware, and the tests are in tests/.

Now someone asks you:

"If I change the authentication function,
what other modules break?"

Can you answer that with what you have? Probably not. To answer you need to know:

What modules import the authentication module (dependency map)
How the request flows through the auth middleware (flow analysis)
Whether there are other modules that replicate the auth logic instead of importing it (pattern analysis)
Whether there are circular dependencies that complicate the change (anti-pattern detection)

That's architecture. It's not "knowing that it exists" — it's "understanding how it connects."

Comprehension that enables decisions

The architecture map isn't an academic document you store and forget. It's a decision tool. Each piece of the map answers a practical question:

Artifact	Question it answers
Dependency map	"If I change X, what other modules are affected?"
Flow analysis	"Where does the data pass through? Where are the bottlenecks?"
Pattern identification	"What structure does the code have? Is it consistent?"
Anti-pattern detection	"Where are the most impactful improvement opportunities?"

Without these artifacts, refactoring decisions are intuitive — "I think I should refactor this module because it looks messy." With them, decisions are informed — "this module has 15 dependents, a circular dependency with the payments module, and it violates the single responsibility principle. Refactoring it first unblocks improvements in 3 more modules."

Claude Code generates, you interpret

A fundamental point of this module: Claude Code generates the maps, diagrams, and analysis. You interpret what they mean and what to do with them.

Claude Code can tell you that user_service.py imports 8 different modules and is imported by 12 others. That's a data point. You decide whether that's a god object that needs to be split, or a legitimate hub that coordinates user operations.

Claude Code can tell you there's a circular dependency between auth and users. That's a finding. You decide whether to extract an interface, invert the dependency, or create an intermediary module.

The AI does the heavy lifting of analysis. The professional judgment is yours.

Anti-patterns are opportunities

An important note about the tone of this module: when you identify anti-patterns in a codebase, you're not criticizing the original author. You're finding improvement opportunities with information the author may not have had when they wrote the code.

Legacy code isn't "bad." It's code that was written with the constraints of the moment: a tight deadline, a small team, requirements that changed, tools that didn't exist. Identifying anti-patterns is a professional act — like a doctor who diagnoses to treat, not to judge.

The Industry Context

Architecture analysis as a professional skill

In modern development teams, the ability to analyze and communicate a system's architecture is a skill that distinguishes levels:

Level	What they can do
Junior	Understands the function they're modifying
Mid-level	Understands the module they work in and its immediate neighbors
Senior	Understands the complete architecture and can explain it to others
Staff/Principal	Can analyze any codebase, create architecture maps, and make informed design decisions

What this module gives you is the toolkit to operate at the Senior/Staff level — not because you change your title, but because you'll have the ability to create architectural representations that inform decisions. And with Claude Code, you can do it in hours instead of weeks.

Why now?

Historically, creating architecture maps was a manual process that required weeks of analysis. You read code, drew diagrams on a whiteboard, updated them when something changed (spoiler: it never got updated). The result was outdated documentation that nobody trusted.

With Claude Code, the process is different:

Manual analysis (2025):
  Read code -> Draw on whiteboard -> Transcribe to Confluence
  -> Go stale in 2 weeks -> Nobody uses it
  Time: 2-4 weeks. Cost: high. Value: decreasing.

Analysis with Claude Code (2026):
  Prompt -> Dependency map generated -> Flow analysis generated
  -> Pattern analysis generated -> Regenerate when the code changes
  Time: 1-3 hours. Cost: low. Value: regenerable.

The key difference isn't just speed — it's that the analysis is regenerable. If the code changes, you re-run the prompts and get an updated map. That makes it practical, not just theoretical.

Self-diagnosis: Where Are You Today?

Quick 5-question test

1. If I asked you to draw the dependency map of your current project, could you do it?

(a) No — I don't know exactly what depends on what
(b) More or less — I know the main dependencies
(c) Yes — I can draw the complete graph with modules and relationships
(d) Not applicable — I'm not working on a project right now

2. Can you trace the complete flow of a request from the entry point to the response?

(a) Only vaguely — I know it passes through some services
(b) The main flows yes, the secondary ones no
(c) Yes, with detail of each step and data transformation
(d) I'm not sure where to start

3. Can you name 3 architectural patterns your current project uses?

(a) I'm not sure what patterns it uses
(b) I can name 1-2 (MVC, for example)
(c) Yes — I can name specific patterns and where they're implemented
(d) I don't know architectural patterns well

4. Have you ever identified an anti-pattern in existing code?

(a) No — I wouldn't know what to look for
(b) Yes, but intuitively ("this looks bad")
(c) Yes — I can name specific anti-patterns and why they're problematic
(d) I've heard the term but haven't applied it

5. Have you used Claude Code to generate architecture diagrams or maps?

(a) No — I only use it to generate code
(b) I've tried, but the results weren't useful
(c) Yes — I generate diagrams regularly with Claude Code
(d) I didn't know you could do that

Interpretation

Mostly (a) or (d): This module opens a completely new capability for you. Every capsule will be eye-opening.
Mostly (b): You have intuition but no method. This module's techniques will give structure to what you already perceive.
Mostly (c): You already have a solid base. This module will give you Claude Code tools to do the analysis faster and more rigorously.

The common denominator

Regardless of your answers, there's something that applies to everyone: most developers don't have an explicit map of their own project's architecture. The understanding is in their head — fragmented, incomplete, and not shareable. This module teaches you to externalize that comprehension into concrete artifacts.

Key Vocabulary

These are the terms you'll use throughout the module. Some are new, others expand on concepts from previous modules:

Term	Definition
Dependency map	A visual or textual representation of which module depends on which. Shows the import relationships between components
Dependency graph	Synonym for dependency map, but emphasizes the graph structure (nodes = modules, edges = dependencies)
Flow analysis	The process of tracing the path that data or requests follow through the system, from input to output
Request flow	A specific case of flow analysis: how an HTTP request travels from the entry point to the response
Data pipeline	The sequence of transformations data undergoes: input -> validation -> processing -> storage -> output
Pattern (architectural)	A recurring structure for organizing code: MVC, service layer, repository, event-driven, etc.
Anti-pattern	A code structure that seems to work but creates problems: circular dependencies, god objects, deep coupling
Circular dependency	A depends on B, and B depends on A. Creates coupling and makes it hard to modify either one
God object	A class or module that does too many things — has too many responsibilities
Fan-out	The number of modules a given module imports. High fan-out = depends on many others
Fan-in	The number of modules that import a given module. High fan-in = many depend on it
Zoom level	The level of detail of the analysis: high-level (components), medium (modules), low (functions)
Architecture map	The complete artifact you produce: dependency map + flow analysis + pattern identification + anti-pattern detection
Mermaid	A text format for generating diagrams (graphs, sequences, flowcharts) that renders in Markdown

You don't need to memorize them all now. You'll use them in each capsule and they'll internalize with practice.

Professional Objective

By the end of this module you'll be able to:

Generate dependency maps with Claude Code — maps that show which module depends on which, at different zoom levels: high-level (3-5 main components), medium (modules within each component), and low (functions within a module).
Create flow analysis for complete requests — from the entry point (route handler) to the response, passing through middleware, services, repositories, and the database. Visualized as sequence diagrams in Mermaid.
Map data flow through the system — how data is transformed: input -> validation -> processing -> storage -> response. Identify where the transformations happen and what format the data has at each step.
Identify architectural patterns — recognize MVC, service layer, repository pattern, event-driven, and other patterns in existing code. Not to judge, but to understand the system's intentional structure.
Detect anti-patterns as opportunities — circular dependencies, god objects, deep coupling, leaky abstractions. Each identified anti-pattern is a refactoring candidate for Phase 2.
Produce a complete architecture map — the integrating artifact that combines dependency map, flow analysis, pattern identification, and anti-pattern detection into a document that informs refactoring decisions.

The shift in perspective

You enter this module knowing how to explore and investigate a codebase. You leave knowing how to create architectural representations that don't just document what exists — they inform what should change. It's the difference between a mechanic who knows how to open the hood and one who has the engine diagrams.

Why this matters for your career

In code reviews: You can identify whether a PR introduces problematic dependencies or breaks established patterns
In planning: You can estimate the real impact of a change: "this affects 3 modules" vs "this affects 15"
In onboarding others: Your architecture map becomes the team's best onboarding tool
In technical decisions: "Rewrite vs refactor" is a question answered with data, not intuition
In interviews: Being able to analyze and communicate a system's architecture is what separates seniors from mid-levels

Module Progression

Module Map

Capsule	Topic	What you'll learn
02	Dependency Maps and Dependency Graphs	Generate dependency maps at different zoom levels. Detect circular dependencies and high fan-out. Compare manual analysis vs Claude Code
03	Flow Analysis — Request->Response and Data Pipelines	Trace requests end-to-end. Analyze data flow and transformations. Generate sequence diagrams with Mermaid
04	Pattern Identification and Anti-Pattern Detection	Recognize architectural patterns in existing code. Detect anti-patterns as refactoring opportunities
05	Project: Architecture Map of a Real Project	Integrate everything into a complete architecture map for a real project. Dependency map + flow analysis + patterns + anti-patterns

Learning flow

Capsule 02: Dependencies           Capsule 03: Flows
(what depends on what)        ->  (how data and requests flow)
        |                                  |
        v                                  v
Capsule 04: Patterns                     |
(what patterns are used             <---+
and which are anti-patterns)
        |
        v
Capsule 05: Project
(everything integrated into
a complete architecture map)

The module's narrative

First you'll learn to map the system's dependencies — which module depends on which, at different levels of detail (capsule 02). With the dependencies mapped, you'll trace how the data and requests flow through those dependencies (capsule 03). With dependencies and flows clear, you'll identify the architectural patterns that organize the code and the anti-patterns that suggest improvements (capsule 04). Finally, you'll integrate everything into a complete architecture map for a real project (capsule 05).

The progression is intentional: you can't analyze flows without knowing the dependencies, you can't identify anti-patterns without understanding the flows, and you can't produce a complete map without the three previous pieces.

Each capsule produces a concrete artifact. You don't leave any capsule with just "knowledge" — you leave with a document you can use, share, and update.

Connection with the Project

Module mini-project: Architecture Map of a Real Project

In capsule 05 you're going to generate a complete architecture analysis package for a real project. Not a theoretical exercise — a project with real dependencies, real flows, and real patterns (and anti-patterns).

What you'll deliver:

✅ A dependency map at two zoom levels (high-level and medium)
✅ Flow analysis of at least 2 critical flows in the system
✅ Pattern identification: what architectural patterns the project uses
✅ Anti-pattern detection: what improvement opportunities you identified
✅ Architecture summary: an integrating document with findings and recommendations

All generated with Claude Code's assistance. The project doesn't evaluate your knowledge of theoretical software architecture — it evaluates your ability to use Claude Code to analyze the architecture that already exists.

Connection with the guide's capstone project (Module 8)

Module 8 is a Full Migration of a Legacy Project. The architecture map you produce here is the second step of that migration (after the Module 1 onboarding):

Module 1: Onboarding -> "I understand what the project does"
Module 2: Explore -> "I can investigate any part"
Module 3: Architecture -> "I have the complete map"           <-- HERE
    |
    v
Module 4: Refactoring -> "I improve the code structure"
Module 5: Migration -> "I change frameworks and languages"
Module 6: Context -> "I handle large projects"
Module 7: Legacy -> "I modernize old code"
    |
    v
Module 8: Capstone Project -> "Everything together in a real migration"

The architecture map informs what to refactor (Module 4), what to migrate (Module 5), and what to modernize (Module 7). Without the map, every improvement decision is a gamble. With it, it's an informed decision.

Direct connection with Module 4

The transition from Module 3 to Module 4 is the most important in the guide:

"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."

Your architecture map becomes the input for the refactoring plan. The circular dependencies you detected become extract-interface targets. The god objects become split candidates. The inconsistent patterns become normalization opportunities.

Limits: What We WON'T Do

To stay focused, this module has clear limits:

❌ You won't design new architecture. This module is about analyzing what exists, not designing what should be. It's not a software architecture class (SOLID, clean architecture, hexagonal, etc.)
❌ You won't modify code. Architectural analysis is read-only. Modifying code comes in Phase 2 (Modules 4-7)
❌ You won't use external diagramming tools. Everything is generated with Claude Code — text and Mermaid. You don't need Lucidchart, draw.io, or other tools
❌ You won't analyze codebases of 100K+ lines. Context management for large projects is Module 6. Here you work with projects of 5K-30K lines
❌ You won't cover deployment architecture (servers, containers, cloud). The scope is the architecture of the source code
❌ You won't study theoretical software architecture. Patterns are mentioned to recognize them, not to learn them from scratch. If you want to go deeper into software architecture, there are excellent resources in the Additional Resources section

What we do cover in depth:

✅ Dependency maps generated with Claude Code at different zoom levels
✅ Flow analysis of requests and data pipelines
✅ Pattern identification in existing code
✅ Anti-pattern detection as a base for refactoring decisions
✅ Architecture map as an integrating artifact and decision tool

Evidence of Success

By the end of the module, these are the measurable criteria that show you completed it successfully:

Mandatory criteria:

Criterion	How to verify it
You can generate a dependency map with Claude Code	You produce a map at two zoom levels for a real project
You can trace a request flow end-to-end	From the entry point to the response, with all the intermediate steps documented
You can identify at least 3 patterns in a codebase	You name them, locate them in the code, and explain why they're used
You can detect at least 2 anti-patterns	You identify them, explain why they're problematic, and suggest an improvement
You produce a complete architecture map	A document with dependency map + flow analysis + patterns + anti-patterns

Excellence criteria (optional):

✅ Your architecture map is clear enough for someone who doesn't know the project to understand it
✅ You identified an anti-pattern that isn't obvious at first glance (not just "this file is large")
✅ Your Mermaid diagrams are renderable and useful (not just syntactically correct)
✅ You connected at least one anti-pattern with a concrete refactoring action

What success looks like in practice

Before this module:

"I explored the codebase, I understand more or less how it works"
-> You can't explain the dependencies
-> You can't predict what breaks if you change something
-> You can't prioritize what to refactor

After this module:

"I have an architecture map of the codebase"
-> The dependency map shows exactly what depends on what
-> The flow analysis traces every request end-to-end
-> The pattern analysis identifies the intentional structure
-> The anti-pattern detection points to concrete improvement opportunities

The final validation question:

If someone shows you a codebase you've never seen and says "I have 2 hours to understand the architecture and decide what to refactor first," can you do it with confidence and produce a document that backs up your decision?

If the answer is yes, you completed this module successfully.

The Core Principle of This Module

Analyze what exists, don't design what should be

This principle distinguishes this module from a software architecture course:

Software Architecture Course	This Module
"This is how you should design your system"	"This is how this system is designed"
Starts from theoretical principles (SOLID, DDD)	Starts from real code that exists
Output: an ideal design	Output: a map of the real thing
Evaluates: "Is the design correct?"	Evaluates: "Can you analyze what's there?"

You're not going to judge whether the architecture is "correct" according to some theoretical standard. You're going to map what exists, identify patterns, detect problems, and document findings. The judgment about what to change comes later, with the information from the map.

The three zoom levels

A common mistake when analyzing architecture is trying to map everything at the same level of detail. A dependency map with 50 modules and 200 arrows is visual noise — it's not a useful map.

This module's approach uses three zoom levels:

Level 1: HIGH-LEVEL (3-5 components)
┌──────────┐    ┌──────────┐    ┌──────────┐
│   API    │───>│ Services │───>│ Database │
└──────────┘    └──────────┘    └──────────┘
"What are the main blocks?"

Level 2: MEDIUM (modules within each component)
┌─ API ─────────────┐    ┌─ Services ──────────┐
│ auth_routes       │───>│ user_service         │
│ user_routes       │───>│ payment_service      │
│ payment_routes    │───>│ notification_service  │
└───────────────────┘    └──────────────────────┘
"What modules are inside each block?"

Level 3: LOW (functions within a module)
┌─ user_service ────────────┐
│ get_user()                │
│ create_user()             │
│ update_user()             │
│ delete_user()             │
│ _validate_email()         │
│ _hash_password()          │
└───────────────────────────┘
"What does each module do internally?"

You choose the level of detail based on your need. To understand the big picture, Level 1. To plan a refactoring, Level 2. To understand a specific function, Level 3.

Claude Code gives you speed, you provide the judgment

Claude Code can generate a dependency map in 30 seconds. But interpreting that map — deciding what it means, what's a problem, and what to do about it — is your professional work.

This module teaches you both parts: how to ask Claude Code to generate the artifacts, and how to read those artifacts to make decisions.

Module Prerequisites

Required knowledge:

✅ Module 1 completed: The method of the 5 questions, onboarding doc, exploration with Claude Code
✅ Module 2 completed: Explore subagent, semantic search, exploration patterns
✅ Intermediate Python: Reading imports, understanding classes and functions, following data flows
✅ Basic Git: Cloning repos, navigating history
✅ Fluent Claude Code: Formulating analysis prompts, interpreting long responses

You don't need:

❌ Previous knowledge of software architecture (SOLID, DDD, hexagonal, etc.)
❌ Experience with diagramming tools
❌ Knowledge of Mermaid syntax (it's explained in the capsules)
❌ Experience with refactoring (that comes in Phase 2)

Setup check

# Check Claude Code
claude --version
# Expected: installed version

# Check Python
python --version
# Expected: Python 3.10+

# Check that you have a project to analyze
# (the one you used in Modules 1-2, or a new one)
ls your-project/
# Expected: the project's files

Estimated Time Distribution

Capsule	Estimated time	Main activity
01 (this one)	10-15 min	Reading: module objectives and context
02	20-25 min	Dependency maps and dependency graphs
03	20-25 min	Flow analysis: request->response and data pipelines
04	20-25 min	Pattern identification and anti-pattern detection
05	40-50 min	Project: architecture map of a real project
Total	~1.75-2.5 hrs

The module is designed to be completed in one long session or two short ones. If you need to split it, the natural pause point is after capsule 03 (flow analysis). The first three capsules build the individual skills; capsule 04 combines them; capsule 05 applies them to a real project.

Summary

✅ This module closes Phase 1: it transforms exploration (M1) and precise access (M2) into documented architectural comprehension
✅ Generate dependency maps at different zoom levels: high-level, medium, and low
✅ Produce flow analysis: how requests and data flow through the system
✅ Identify architectural patterns and detect anti-patterns as refactoring opportunities
✅ All generated with Claude Code — you interpret and decide what to do with the findings
✅ The focus is analyzing what exists, not designing what should be
✅ The architecture map you produce is the direct input for Module 4 (Refactoring)
✅ Anti-patterns are improvement opportunities, not criticisms of the original author

Additional Resources

Working Effectively with Legacy Code — Michael Feathers — The reference book on understanding and working with existing code. Fundamental context for all architectural analysis.
Software Architecture in Practice — Bass, Clements & Kazman — A complete software architecture reference. Useful if you want to go deeper into the patterns you recognize in this module.
Mermaid Documentation — Official Mermaid documentation for diagrams. You'll use this format to generate dependency graphs and sequence diagrams.
Visualizing Software Architecture — Simon Brown (C4 Model) — The C4 model for visualizing architecture at different zoom levels. A direct inspiration for this module's approach.
Claude Code Documentation — Anthropic — Official Claude Code documentation. Code analysis and diagram generation features.
Software Design X-Rays — Adam Tornhill — Codebase analysis using version control data. Complements the module's AI analysis.
Refactoring Guru — Anti-Patterns — A visual catalog of anti-patterns with explanations and solutions. A quick reference for capsule 04.

Next capsule: Dependency Maps and Dependency Graphs — which module depends on which, at different zoom levels, generated with Claude Code.

Module 3, Capsule 01 — Refactoring & Legacy Code with Claude Code Guide

← PreviousModule Project: Codebase Exploration with Explore Next →Dependency Maps and Dependency Graphs