Software Diagramming Techniques: From Napkin Sketches to Production Documentation
Goal: Master the art and science of software diagramming. You will learn to communicate complex systems visually, choose the right diagram type for each audience, and automate diagram generation as code. By the end, you will be the person who can take any vague architecture discussion and turn it into a crystal-clear visual that everyone understands.
Why Diagramming Matters
Software is invisible. Unlike bridges or buildings, you cannot walk around a codebase and see its structure. This is why diagrams are the universal language of software architecture.
Yet most developers treat diagramming as an afterthought:
- They draw boxes and arrows with no consistent notation
- They create “one diagram to rule them all” that confuses everyone
- They let diagrams rot while the code evolves
- They use expensive tools that create unmaintainable artifacts
The Cost of Poor Communication
Without Clear Diagrams With Clear Diagrams
+---------------------------+ +---------------------------+
| 2-hour architecture | | 15-minute visual review |
| meeting, no resolution | | Everyone aligned |
+---------------------------+ +---------------------------+
| New dev onboarding: | | New dev onboarding: |
| 3 months to understand | | 2 weeks to contribute |
| the system | | meaningfully |
+---------------------------+ +---------------------------+
| "What talks to what?" | | "I can see exactly how |
| debates during outages | | this flows" |
+---------------------------+ +---------------------------+
| Technical debt invisible | | Architecture smells |
| until production breaks | | visible in diagrams |
+---------------------------+ +---------------------------+
Statistics That Matter
- 65% of people are visual learners - text-only documentation fails them
- Code documentation becomes outdated in weeks - diagram-as-code keeps them in sync
- Architecture decisions without visual context take 3x longer to approve (Martin Fowler, “Patterns of Enterprise Application Architecture”)
- Teams with standardized diagramming spend 40% less time in alignment meetings (Thoughtworks Technology Radar)
The Diagramming Spectrum
ABSTRACTION LEVEL
HIGH +--------------------------------------------------+
| |
| C4 Context Diagram Use Case Diagram |
| (Executive Level) (Business Requirements)|
| |
+--------------------------------------------------+
| |
| C4 Container Diagram Component Diagram |
| (Technical Lead Level) (Module Boundaries) |
| |
+--------------------------------------------------+
| |
| Sequence Diagram State Machine |
| (Developer Level) (Behavior Detail) |
| |
+--------------------------------------------------+
| |
| Class Diagram ER Diagram |
| (Implementation Detail) (Data Structure) |
| |
LOW +--------------------------------------------------+
AUDIENCE: Business <----------------> Technical
Prerequisites & Background Knowledge
Essential Prerequisites
Before starting these projects, you should be able to:
- Read and write basic code in at least one language
- Understand client-server architecture at a high level
- Use Git for version control (we will store diagrams as code)
- Navigate a terminal for tool installation
Self-Assessment Questions
Answer these before starting. If you struggle, review the referenced materials:
- What is the difference between synchronous and asynchronous communication?
- Why it matters: Sequence diagrams depend on this distinction.
- What is a database schema?
- Why it matters: ER diagrams model data relationships.
- What is an API?
- Why it matters: Many diagrams show API boundaries.
- Can you explain what a “microservice” is?
- Why it matters: Container diagrams separate services.
Development Environment Setup
You will need:
# Node.js (for Mermaid CLI)
node --version # Should be 18+
# Python (for diagrams library)
python3 --version # Should be 3.9+
# D2 Language
# macOS
brew install d2
# Linux
curl -fsSL https://d2lang.com/install.sh | sh -s --
# PlantUML (requires Java)
java -version # Should be 11+
# Install PlantUML JAR or use Docker:
docker pull plantuml/plantuml-server
# Graphviz (for PlantUML and other tools)
brew install graphviz # macOS
sudo apt install graphviz # Ubuntu
Time Investment
| Your Background | Expected Time |
|---|---|
| New to diagramming | 6-8 weeks (all projects) |
| Some UML experience | 4-5 weeks |
| Architect wanting depth | 3-4 weeks (focus on C4, ADRs) |
Core Concept Analysis
1. The Purpose Hierarchy
Every diagram answers a specific question for a specific audience:
+----------------------------------------------------------------+
| DIAGRAM PURPOSE |
+----------------------------------------------------------------+
| |
| WHAT exists? |
| +----------------------------------------------------------+ |
| | Class Diagrams, Component Diagrams, ER Diagrams | |
| | "These are the pieces of the system" | |
| +----------------------------------------------------------+ |
| |
| HOW does it behave? |
| +----------------------------------------------------------+ |
| | Sequence Diagrams, State Machines, Activity Diagrams | |
| | "This is how the pieces interact over time" | |
| +----------------------------------------------------------+ |
| |
| WHERE does it run? |
| +----------------------------------------------------------+ |
| | Deployment Diagrams, C4 Container Diagrams | |
| | "This is how it maps to infrastructure" | |
| +----------------------------------------------------------+ |
| |
| WHY was it designed this way? |
| +----------------------------------------------------------+ |
| | Architecture Decision Records (ADRs) | |
| | "This is the reasoning behind the structure" | |
| +----------------------------------------------------------+ |
| |
+----------------------------------------------------------------+
2. Notation Systems
Different notations solve different problems:
+-------------------+------------------------+------------------------+
| NOTATION | STRENGTHS | WEAKNESSES |
+-------------------+------------------------+------------------------+
| UML | Standardized, mature | Complex, can be |
| (Unified Modeling | Many diagram types | overwhelming |
| Language) | Tool support | Not always intuitive |
+-------------------+------------------------+------------------------+
| C4 Model | Simple, hierarchical | Less detailed than |
| | Audience-focused | UML for code-level |
| | Easy to learn | structures |
+-------------------+------------------------+------------------------+
| Informal Boxes | Quick, accessible | Inconsistent, no |
| & Arrows | No learning curve | standard meaning |
+-------------------+------------------------+------------------------+
| ER Diagrams | Standard for databases | Only for data |
| (Chen/Crow's Foot)| Clear cardinality | modeling |
+-------------------+------------------------+------------------------+
3. Diagram-as-Code Philosophy
The revolution: treat diagrams like source code.
Traditional Approach Diagram-as-Code
+---------------------------+ +---------------------------+
| Binary file (.vsdx, .png) | | Text file (.mmd, .puml) |
| Cannot diff changes | | Git diffs show changes |
| Cannot review in PRs | | Review diagrams in PRs |
| Manual exports | | CI/CD generates images |
| Single source of truth? | | Diagrams live with code |
+---------------------------+ +---------------------------+
Version Control Comparison:
Binary Diagram:
git diff architecture.png
> Binary files differ # Useless!
Text Diagram:
git diff architecture.mmd
> - PaymentService -> Database
> + PaymentService -> Cache -> Database
# Clear change!
4. The C4 Model Hierarchy
The C4 Model by Simon Brown is the most practical architecture diagramming approach:
C4 MODEL ZOOM LEVELS
Level 1: CONTEXT
+---------------------------------------------------------------+
| |
| +--------+ +------------------+ +--------+ |
| | User |----->| Your System |----->| External| |
| | (Actor)| | (Black Box) | | System | |
| +--------+ +------------------+ +--------+ |
| |
| Question: What is this system and who uses it? |
+---------------------------------------------------------------+
|
| Zoom In
v
Level 2: CONTAINER
+---------------------------------------------------------------+
| Your System (Opened) |
| +-------------+ +-------------+ +-------------+ |
| | Web App | | API Server | | Database | |
| | (React) |->| (Node.js) |->| (PostgreSQL)| |
| +-------------+ +-------------+ +-------------+ |
| |
| Question: What are the major technical pieces? |
+---------------------------------------------------------------+
|
| Zoom In
v
Level 3: COMPONENT
+---------------------------------------------------------------+
| API Server (Opened) |
| +-------------+ +-------------+ +-------------+ |
| | Auth | | Payment | | Notification| |
| | Controller | | Service | | Service | |
| +-------------+ +-------------+ +-------------+ |
| |
| Question: What are the major code modules? |
+---------------------------------------------------------------+
|
| Zoom In
v
Level 4: CODE (Optional)
+---------------------------------------------------------------+
| Payment Service (Opened) |
| |
| UML Class Diagram or similar showing implementation |
| |
| Question: How is this component implemented? |
+---------------------------------------------------------------+
5. Sequence Diagram Mental Model
Sequence diagrams show interactions over time:
SEQUENCE DIAGRAM ANATOMY
PARTICIPANTS (across the top)
|
v
+--------+ +--------+ +--------+
| Client | | Server | | Database|
+---+----+ +---+----+ +----+----+
| | |
LIFELINES| | | TIME
(vertical|------------->| | |
lines) | 1. Request | | |
| |-------------->| |
| | 2. Query | v
| |<--------------|
| | 3. Result |
|<-------------| |
| 4. Response | |
| | |
MESSAGES (horizontal arrows)
- Solid line = synchronous call
- Dashed line = return/response
- Open arrowhead = async message
ACTIVATION BARS (rectangles on lifelines)
- Show when a participant is "active"
6. State Machine Fundamentals
State machines model behavior over time:
STATE MACHINE ANATOMY
INITIAL STATE (filled circle)
|
v
+---------------+
| IDLE |<-----------------------------+
| | |
+-------+-------+ |
| |
| event: START |
v |
+---------------+ +---------------+ |
| RUNNING |-------->| PAUSED | |
| | PAUSE | | |
+---------------+ +-------+-------+ |
| | |
| COMPLETE | RESUME |
v | |
+---------------+ | |
| FINISHED |-----------------+ |
| | |
+---------------+ |
| |
| RESET |
+--------------------------------------+
FINAL STATE (circle with inner dot)
TRANSITIONS:
event [guard] / action
- event: What triggers the transition
- guard: Condition that must be true (optional)
- action: What happens during transition (optional)
Concept Summary Table
| Concept | What You Must Internalize |
|---|---|
| Abstraction Levels | Different audiences need different zoom levels. Never show code to executives. |
| Notation Standards | Consistent symbols create shared understanding. Arbitrary boxes fail. |
| Diagram-as-Code | Text-based diagrams enable version control, review, and automation. |
| C4 Model | Four zoom levels (Context, Container, Component, Code) serve different purposes. |
| Sequence Diagrams | Time flows top-to-bottom. Messages flow left-to-right. |
| State Machines | States are nouns. Transitions are verbs (events). |
| ER Diagrams | Cardinality (1:1, 1:N, M:N) is the critical information. |
| ADRs | Decisions need context, not just conclusions. |
Deep Dive Reading by Concept
Concept 1: Architecture Visualization Fundamentals
| Topic | Book & Chapter |
|---|---|
| Why Architecture Matters | “Software Architecture in Practice” by Bass, Clements, Kazman - Ch. 1: “What Is Software Architecture?” |
| Documenting Architecture | “Software Architecture in Practice” - Ch. 22: “Architecture Documentation” |
| Views and Beyond | “Documenting Software Architectures” by Clements et al. - Ch. 1-2: “Overview” |
| Architecture Communication | “The Software Architect Elevator” by Gregor Hohpe - Ch. 6: “Drawing” |
Concept 2: UML Fundamentals
| Topic | Book & Chapter |
|---|---|
| UML Overview | “UML Distilled” by Martin Fowler - Ch. 1-2: “Introduction” |
| Class Diagrams | “UML Distilled” - Ch. 3: “Class Diagrams” |
| Sequence Diagrams | “UML Distilled” - Ch. 4: “Sequence Diagrams” |
| State Machines | “UML Distilled” - Ch. 10: “State Machine Diagrams” |
| Use Case Diagrams | “UML Distilled” - Ch. 9: “Use Cases” |
Concept 3: The C4 Model
| Topic | Book & Chapter |
|---|---|
| C4 Introduction | “The C4 Model for Software Architecture” by Simon Brown - Online Resource |
| Context Diagrams | “Software Architecture for Developers” by Simon Brown - Part 2: “Visualising” |
| Container Diagrams | “Software Architecture for Developers” - Part 2: “Container Diagrams” |
| Diagramming Principles | “The Art of Visualising Software Architecture” by Simon Brown |
Concept 4: Data Modeling
| Topic | Book & Chapter |
|---|---|
| ER Diagram Notation | “Database Design for Mere Mortals” by Hernandez - Ch. 6: “Relationships” |
| Cardinality Rules | “SQL and Relational Theory” by C.J. Date - Ch. 4: “Relations” |
| Data Flow Diagrams | “Structured Analysis and System Specification” by Tom DeMarco |
Concept 5: Diagram-as-Code
| Topic | Book & Chapter |
|---|---|
| Documentation as Code | “Docs as Code” by Anne Gentle - All chapters |
| Mermaid Syntax | Mermaid Official Documentation - Getting Started |
| PlantUML Reference | PlantUML Official Guide - Language Reference |
Concept 6: Architecture Decisions
| Topic | Book & Chapter |
|---|---|
| ADR Fundamentals | “Design It!” by Michael Keeling - Ch. 13: “Empower the Architect” |
| Decision Making | “Software Architecture: The Hard Parts” by Richards & Ford - Ch. 2: “Decisions” |
| Trade-off Analysis | “Fundamentals of Software Architecture” by Richards & Ford - Ch. 19: “Architecture Decisions” |
Essential Reading Order
Phase 1: Foundations (Before Starting Projects)
- “UML Distilled” - Ch. 1-2: Why visual modeling matters
- “Software Architecture for Developers” - Part 2: C4 Model introduction
- Mermaid Documentation - Quick start guide
Phase 2: Core Techniques (During Projects 1-6)
- “UML Distilled” - Ch. 3-4: Class and Sequence diagrams
- “Software Architecture in Practice” - Ch. 22: Documentation strategies
- “The Art of Visualising Software Architecture” - Diagramming anti-patterns
Phase 3: Advanced Patterns (During Projects 7-12)
- “Documenting Software Architectures” - Views and viewpoints
- “Design It!” - Ch. 13: ADRs
- PlantUML Official Guide - Advanced features
Phase 4: Automation & Integration (Projects 13-17)
- “Docs as Code” - Treating documentation as software
- D2 Language Documentation - Modern diagram-as-code
- “Software Architecture: The Hard Parts” - Ch. 2: Documenting trade-offs
Quick Start Guide
If you’re overwhelmed, do this in your first 48 hours:
- Install Mermaid Live Editor (https://mermaid.live) - no installation needed
- Draw a simple sequence diagram of “User logs in” - 10 minutes
- Read C4 Model introduction at c4model.com - 30 minutes
- Draw a Context Diagram of a system you know - 20 minutes
- Try Excalidraw (https://excalidraw.com) for informal sketching - 10 minutes
Your first artifact: A Context Diagram of a web application you use daily.
Recommended Learning Paths
Path A: The Pragmatic Developer (4 weeks)
| Week | Projects | Focus |
|---|---|---|
| 1 | 1, 2, 9 | UML basics + Mermaid |
| 2 | 3, 4, 10 | Behavior diagrams + PlantUML |
| 3 | 5, 6, 11 | C4 Model + D2 |
| 4 | 14, 15 | ADRs + API documentation |
Path B: The Architect (5 weeks)
| Week | Projects | Focus |
|---|---|---|
| 1 | 5, 6, 7, 8 | C4 Model deep dive |
| 2 | 3, 4 | Behavioral modeling |
| 3 | 14, 17 | ADRs + Threat modeling |
| 4 | 11, 12 | Python automation |
| 5 | 15, 16 | API + System context |
Path C: Documentation Lead (3 weeks)
| Week | Projects | Focus |
|---|---|---|
| 1 | 9, 10, 11 | All diagram-as-code tools |
| 2 | 13, 14 | ASCII + ADRs |
| 3 | 15, 16 | API + Context diagrams |
Project List
These projects build from fundamental notation to automated documentation pipelines.
Project 1: UML Class Diagram Fundamentals
| Attribute | Value |
|---|---|
| Difficulty | Beginner |
| Time Estimate | 1-2 days |
| Tools | draw.io, Mermaid |
| Key Concept | Static structure visualization |
What you’ll build: A class diagram for a library management system showing Book, Author, Member, and Loan entities with relationships, attributes, and methods.
Why it teaches diagramming: Class diagrams are the foundation of structural modeling. Understanding visibility modifiers, associations, and inheritance translates to all other diagram types.
Core challenges you’ll face:
- Choosing the right relationship: When to use association vs aggregation vs composition
- Attribute visibility: Public (+), private (-), protected (#)
- Method signatures: Showing types and parameters cleanly
- Cardinality notation: 1..* vs 0..1 vs *
Real World Outcome
Your diagram will clearly show:
+-------------------+ +-------------------+
| Author | | Book |
+-------------------+ +-------------------+
| - id: UUID | 1..* | - isbn: String |
| - name: String |<>-------| - title: String |
| - birthYear: int | | - publishedYear |
+-------------------+ +-------------------+
| + getBooks(): List| | + getAuthor() |
| + getBio(): String| | + isAvailable() |
+-------------------+ +-------------------+
|
| 0..*
|
+-------v-----------+
| Loan |
+-------------------+
| - loanDate: Date |
| - dueDate: Date |
| - returnDate: Date|
+-------------------+
| + isOverdue(): bool|
| + calculateFine() |
+-------------------+
|
| 1
|
+-------v-----------+
| Member |
+-------------------+
| - memberId: String|
| - name: String |
| - email: String |
+-------------------+
| + borrowBook() |
| + returnBook() |
| + getActiveLoans()|
+-------------------+
The Core Question You’re Answering
“How do I communicate the static structure of a system so that developers can understand entity relationships at a glance?”
Concepts You Must Understand First
- What is a class? An object template with attributes (data) and methods (behavior).
- What is encapsulation? Hiding implementation details behind an interface.
- What is the difference between association, aggregation, and composition?
- Association: “uses” (Student uses Library)
- Aggregation: “has” with independent lifecycle (Team has Players)
- Composition: “owns” with dependent lifecycle (House owns Rooms)
Questions to Guide Your Design
- Which entities are independent vs dependent on others?
- What is the cardinality of each relationship?
- What methods expose the entity’s behavior?
- Which attributes should be public vs private?
Thinking Exercise
Before drawing, list all entities in a library system. For each pair, ask:
- Do they relate?
- Who owns whom?
- How many of A can relate to how many of B?
The Interview Questions They’ll Ask
- “What is the difference between aggregation and composition?”
- Aggregation: Child can exist independently (Player can exist without Team)
- Composition: Child cannot exist independently (Room cannot exist without House)
- “Why use private attributes with getter methods?”
- Encapsulation allows changing internal representation without breaking clients
- “When would you NOT use a class diagram?”
- For behavior (use sequence/state diagrams)
- For deployment (use deployment diagrams)
- For high-level overview (use C4)
- “How do you show an interface in UML?”
- Stereotype: «interface» above the name
- Dashed line with open arrowhead for implementation
- “What does the diamond on a relationship line mean?”
- Open diamond: Aggregation (weak ownership)
- Filled diamond: Composition (strong ownership)
Hints in Layers
Hint 1: Start with nouns from the problem domain. Each noun is a potential class.
Hint 2: Use draw.io’s UML Class library. Each box has sections: name, attributes, methods.
Hint 3: For cardinality, write it at BOTH ends of the line. “1” on Author, “1..*” on Book means one author has many books.
Hint 4: In Mermaid, use:
classDiagram
Author "1" --o "*" Book : writes
class Author {
-String name
+getBooks() List~Book~
}
Books That Will Help
| Topic | Book & Chapter |
|---|---|
| Class diagram notation | “UML Distilled” Ch. 3 |
| Relationship types | “UML Distilled” Ch. 5 |
| Object-oriented design | “Head First Design Patterns” Ch. 1 |
Common Pitfalls & Debugging
| Problem | Cause | Fix |
|---|---|---|
| Lines crossing messily | Poor layout | Place related classes adjacent |
| Too many attributes shown | Over-detailing | Show only key attributes |
| Missing cardinality | Incomplete thinking | Always ask “how many?” at each end |
| Circular dependencies | Tangled design | Refactor to depend on abstractions |
Learning Milestones
- Novice: Can draw boxes with attributes
- Intermediate: Uses correct relationship arrows and cardinality
- Advanced: Diagram clearly communicates design decisions
Project 2: Sequence Diagrams for API Flows
| Attribute | Value |
|---|---|
| Difficulty | Beginner |
| Time Estimate | 1-2 days |
| Tools | Mermaid, PlantUML |
| Key Concept | Interaction over time |
What you’ll build: A sequence diagram showing an OAuth2 authentication flow: User -> Frontend -> Auth Server -> Backend -> Database.
Why it teaches diagramming: Sequence diagrams are the most practical diagram for developers. They show exactly what calls what, in what order, with what data.
Core challenges you’ll face:
- Participant ordering: Left-to-right positioning matters
- Sync vs async messages: Solid vs dashed lines
- Activation bars: Showing when something is “doing work”
- Loops and conditionals: Alt/opt/loop fragments
Real World Outcome
+--------+ +---------+ +------------+ +---------+ +----------+
| User | | Frontend| | AuthServer | | Backend | | Database |
+---+----+ +----+----+ +-----+------+ +----+----+ +----+-----+
| | | | |
| 1. Click Login| | | |
|-------------->| | | |
| | 2. Redirect to OAuth | |
| |--------------->| | |
| | | | |
| 3. Enter credentials | | |
|------------------------------ >| | |
| | | | |
| | 4. Auth code | | |
| |<---------------| | |
| | | | |
| | 5. Exchange code for token | |
| |--------------------------------->| |
| | | | |
| | | 6. Validate code| |
| | |<----------------| |
| | | | |
| | | 7. Return token | |
| | |---------------->| |
| | | | |
| | | | 8. Store session
| | | |-------------->|
| | | | |
| | | | 9. Confirm |
| | | |<--------------|
| | | | |
| | 10. Return JWT | | |
| |<---------------------------------| |
| | | | |
| 11. Show dashboard | | |
|<--------------| | | |
| | | | |
The Core Question You’re Answering
“How do I show the exact sequence of calls and responses for a complex interaction?”
Concepts You Must Understand First
- What is a synchronous call? Caller waits for response.
- What is an asynchronous call? Caller continues without waiting.
- What is OAuth2? Authorization protocol with code/token exchange.
Questions to Guide Your Design
- Which system initiates the flow?
- What data is passed in each message?
- Where do error paths diverge?
- Which calls are synchronous vs asynchronous?
The Interview Questions They’ll Ask
- “How do you show parallel execution in a sequence diagram?”
- Use the
parfragment with parallel regions
- Use the
- “What’s the difference between a solid and dashed arrow?”
- Solid: Synchronous call
- Dashed: Return/response
- “How do you show optional paths?”
- Use
opt(optional) oralt(alternative) fragments
- Use
- “How do you show a loop?”
- Use
loopfragment with condition
- Use
- “When should you NOT use a sequence diagram?”
- For static structure (use class diagrams)
- For user stories (use use case diagrams)
Hints in Layers
Hint 1: List all participants first. Order them left-to-right by typical call direction.
Hint 2: In Mermaid:
sequenceDiagram
participant U as User
participant F as Frontend
participant A as AuthServer
U->>F: Click Login
F->>A: Redirect to OAuth
A-->>F: Auth code
Hint 3: Use -->> for return messages (dashed line).
Hint 4: For conditionals:
alt is valid
A->>B: Success
else is invalid
A->>B: Error
end
Books That Will Help
| Topic | Book & Chapter |
|---|---|
| Sequence diagram notation | “UML Distilled” Ch. 4 |
| Interaction fragments | “UML Distilled” Ch. 4, “Fragments” section |
| API design | “Web API Design” by Brian Mulloy |
Project 3: State Machine for Order Lifecycle
| Attribute | Value |
|---|---|
| Difficulty | Intermediate |
| Time Estimate | 2-3 days |
| Tools | Mermaid, PlantUML, XState Visualizer |
| Key Concept | Behavior modeling |
What you’ll build: A state machine diagram for an e-commerce order: Created -> Paid -> Shipped -> Delivered, with cancellation and return paths.
Why it teaches diagramming: State machines force you to think about ALL possible states and transitions. They reveal edge cases that narrative descriptions miss.
Core challenges you’ll face:
- Identifying all states: Not just the happy path
- Guard conditions: When can a transition occur?
- Actions: What happens during a transition?
- Composite states: States within states
Real World Outcome
+-------------------+
| [Initial] |
+--------+----------+
|
| create()
v
+--------+----------+
+--->| CREATED |<---+
| +--------+----------+ |
| | |
| payment_received() | cancel()
| v |
| +--------+----------+ |
| | PAID |----+
| +--------+----------+
| |
| ship()
modify() | v
[count<3] | +--------+----------+
| | SHIPPED |
| +--------+----------+
| |
| deliver()
| v
| +--------+----------+ return_requested()
+----+ DELIVERED +------------------------+
+--------+----------+ |
| |
| v
| +--------+----------+
| | RETURN_ |
| | REQUESTED |
| +--------+----------+
| |
| approve_return()
| v
| +--------+----------+
| | RETURNED |
| +--------+----------+
| |
+-----------------------------------+
|
v
+--------+----------+
| [Final] |
+-------------------+
The Core Question You’re Answering
“What are ALL the states an entity can be in, and what causes transitions between them?”
Concepts You Must Understand First
- What is a finite state machine (FSM)? A model with a finite number of states, events, and transitions.
- What is a guard condition? A boolean that must be true for a transition to occur.
- What is an action? Side effect that occurs during a transition.
Questions to Guide Your Design
- What is the initial state?
- What are all possible final states?
- For each state, what events can occur?
- Are there any impossible transitions? (These reveal business rules)
The Interview Questions They’ll Ask
- “How do you handle an event that can happen in multiple states?”
- Define the transition from each valid source state
- Or use a composite state if behavior is identical
- “What’s the difference between a state and a status?”
- Status is data. State defines allowed behavior.
- An order with status=”shipped” means different things than state=SHIPPED
- “How do you model nested states?”
- Use composite (hierarchical) states
- Child states inherit parent’s outgoing transitions
- “How do state machines help prevent bugs?”
- Enforce that invalid transitions cannot occur
- Make all edge cases explicit
- “When would you use a state machine vs a simple status field?”
- State machine: Complex transitions, guards, actions
- Status field: Simple linear progression
Hints in Layers
Hint 1: Draw the happy path first: Created -> Paid -> Shipped -> Delivered.
Hint 2: Then ask: “What can go wrong at each step?” Add cancellation, returns, payment failures.
Hint 3: In Mermaid:
stateDiagram-v2
[*] --> Created
Created --> Paid : payment_received
Paid --> Shipped : ship
Paid --> Created : payment_failed
Hint 4: For guards:
stateDiagram-v2
Created --> Created : modify [count < 3]
Books That Will Help
| Topic | Book & Chapter |
|---|---|
| State machine notation | “UML Distilled” Ch. 10 |
| State machine design | “Domain-Driven Design” by Eric Evans - Ch. 10 |
| XState patterns | “XState Documentation” - Tutorials |
Project 4: Activity Diagram for Business Process
| Attribute | Value |
|---|---|
| Difficulty | Intermediate |
| Time Estimate | 2 days |
| Tools | draw.io, Lucidchart, PlantUML |
| Key Concept | Workflow visualization |
What you’ll build: An activity diagram for an employee expense reimbursement process with parallel approvals, decision points, and swimlanes for different roles.
Why it teaches diagramming: Activity diagrams are flowcharts on steroids. They show parallel execution, decision points, and role responsibilities - critical for business process modeling.
Core challenges you’ll face:
- Swimlanes: Showing who does what
- Fork/Join bars: Parallel execution
- Decision diamonds: Branching logic
- Merge vs Join: Convergence semantics
Real World Outcome
| Employee | Manager | Finance | System |
+==============+================+==============+==============+
| | | | |
| [*] Start | | | |
| | | | | |
| v | | | |
| +----------+ | | | |
| | Submit | | | | |
| | Expense | | | | |
| +----+-----+ | | | |
| | | | | |
| +------>| +------------+ | | |
| | | Review | | | |
| | | Request | | | |
| | +-----+------+ | | |
| | | | | |
| | <Decision> | | |
| | / \ | | |
| | Yes No | | |
| | | | | | |
| +---------+ | +--+-->+--------+ | |
| | | | Reject | | |
| v | +---+----+ | |
| +-------+ | | | |
| | Revise|<------+---------------------+ | |
| +---+---+ | | |
| | | | |
| +-----------+ | |
| | | |
| | Approve | |
| +--------------------------->| +----------+ |
| | | | Verify | |
| | | | Policy | |
| | | +----+-----+ |
| | | | |
| | | <Decision> |
| | | / \ |
| | | Ok Flag |
| | | | | |
| | | v v |
| | | Process Audit|
| | | \ / |
| | | \ / |
| | | \ / |
| | +------+-------+
| | | |
| | +------>|
| | |
| | +-----------+
| | | Generate |
| | | Payment |
| | +-----+-----+
| | |
| [*] End <-------------------------------------------+
| | | | |
The Core Question You’re Answering
“How do I visualize a process with multiple actors, decisions, and parallel paths?”
Concepts You Must Understand First
- What is a swimlane? A visual partition showing which actor performs each action.
- What is a fork? Splitting into parallel paths.
- What is a join? Synchronizing parallel paths.
- What is the difference between merge and join? Merge = any path continues. Join = all paths must complete.
The Interview Questions They’ll Ask
- “How do you show that two activities happen at the same time?”
- Use a fork bar (horizontal bar) splitting into parallel paths
- Use a join bar where they synchronize
- “What’s the difference between an activity and an action?”
- Action: Atomic, cannot be broken down
- Activity: Can contain multiple actions
- “When would you use an activity diagram vs a sequence diagram?”
- Activity: Focus on the process flow and decisions
- Sequence: Focus on message passing between objects
- “How do you handle exception paths?”
- Interruptible regions with interruption edges
- Or explicit decision diamonds for error conditions
Hints in Layers
Hint 1: List all roles (swimlanes) first: Employee, Manager, Finance, System.
Hint 2: Map the happy path through all swimlanes.
Hint 3: Add decision points and alternative paths.
Hint 4: In PlantUML:
@startuml
|Employee|
start
:Submit Expense;
|Manager|
:Review Request;
if (Approved?) then (yes)
|Finance|
:Process Payment;
else (no)
|Employee|
:Revise Request;
endif
@enduml
Project 5: C4 Context Diagram
| Attribute | Value |
|---|---|
| Difficulty | Beginner |
| Time Estimate | 1 day |
| Tools | Structurizr, draw.io, Mermaid |
| Key Concept | System boundaries |
What you’ll build: A C4 Context diagram for a food delivery platform showing the system, users (customers, restaurants, drivers), and external systems (payment gateway, maps API, SMS gateway).
Why it teaches diagramming: Context diagrams are the most important diagram for communication. They answer: “What is this system and how does it fit into the world?”
Core challenges you’ll face:
- Determining scope: What is “inside” vs “outside” the system?
- Identifying actors: Human users vs system users
- Labeling relationships: Clear, action-oriented descriptions
- Avoiding implementation details: Stay at 30,000 feet
Real World Outcome
+------------------------------------------------------------------+
| C4 CONTEXT DIAGRAM |
| Food Delivery Platform |
+------------------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| | Customer | | Restaurant | |
| | [Person] | | Owner | |
| | | | [Person] | |
| | Orders food | | | |
| | via mobile app | | Manages menu | |
| +-------+--------+ | Accepts orders | |
| | +-------+--------+ |
| | | |
| | Places order | Manages |
| | Tracks delivery | restaurant |
| v v |
| +-------+-------------------------------------------+--------+ |
| | | |
| | Food Delivery Platform | |
| | [Software System] | |
| | | |
| | Connects customers with restaurants | |
| | Manages delivery logistics | |
| | | |
| +-------+-------------------------------------------+--------+ |
| | | |
| | | |
| v v |
| +-------+--------+ +-------+--------+ |
| | Delivery | | Payment | |
| | Driver | | Gateway | |
| | [Person] | | [Ext System] | |
| | | | | |
| | Picks up and | | Processes | |
| | delivers food | | payments | |
| +----------------+ +-------+--------+ |
| | |
| +---------------+ |
| | |
| +-------v--------+ |
| | Maps API | |
| | [Ext System] | |
| | | |
| | Provides | |
| | routing and | |
| | ETA | |
| +----------------+ |
| |
+------------------------------------------------------------------+
LEGEND:
+------------+ +------------+ +------------------+
| [Person] | | [Software | | [External System]|
| Human | | System] | | Third party |
| user | | Your scope | | dependency |
+------------+ +------------+ +------------------+
The Core Question You’re Answering
“What is this system, who uses it, and what does it depend on?”
Concepts You Must Understand First
- What is system scope? The boundary of what you’re responsible for.
- What is an actor? Any entity that interacts with the system.
- What is an external system? Something you integrate with but don’t control.
Questions to Guide Your Design
- Who are ALL the users of this system? (Human and machine)
- What external systems does it integrate with?
- What is the core value proposition? (One sentence description)
- What is explicitly OUT of scope?
The Interview Questions They’ll Ask
- “Why start with a context diagram?”
- Sets the scope for all other diagrams
- Ensures alignment on what the system IS
- Easy for non-technical stakeholders to understand
- “How detailed should relationship labels be?”
- Action-oriented: “Places orders”, not just “uses”
- Include key data: “Sends order details via REST API”
- “When is something an external system vs part of your system?”
- External: You don’t control it, you integrate with it
- Internal: You own the code, deployment, and roadmap
- “How many systems should be on a context diagram?”
- Typically 5-15 boxes
- If more, you might be zooming in too much
Hints in Layers
Hint 1: Put your system in the center. Everything else orbits it.
Hint 2: Use different shapes/colors for People vs External Systems.
Hint 3: Every arrow needs a label describing the interaction.
Hint 4: In Structurizr DSL:
workspace {
model {
customer = person "Customer" "Orders food via mobile app"
deliveryPlatform = softwareSystem "Food Delivery Platform" {
description "Connects customers with restaurants"
}
paymentGateway = softwareSystem "Payment Gateway" "External" {
tags "External"
}
customer -> deliveryPlatform "Places order, tracks delivery"
deliveryPlatform -> paymentGateway "Processes payments via"
}
}
Project 6: C4 Container Diagram
| Attribute | Value |
|---|---|
| Difficulty | Intermediate |
| Time Estimate | 2 days |
| Tools | Structurizr, draw.io, IcePanel |
| Key Concept | Technical decomposition |
What you’ll build: A C4 Container diagram zooming into the Food Delivery Platform from Project 5, showing: Mobile App, Web App, API Gateway, Order Service, Delivery Service, Restaurant Service, PostgreSQL Database, Redis Cache, and Message Queue.
Why it teaches diagramming: Container diagrams show the high-level technology decisions. This is what architects discuss: “Should we add a cache here? Do we need a message queue?”
Core challenges you’ll face:
- Defining containers: Applications, data stores, message brokers
- Showing technology choices: “(React)”, “(Node.js)”, “(PostgreSQL)”
- Inter-container communication: REST, gRPC, async messaging
- Not going too deep: Components come later
Real World Outcome
+------------------------------------------------------------------------+
| Food Delivery Platform [System] |
+------------------------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| | Mobile App | | Web App | |
| | [Container] | | [Container] | |
| | (React | | (React SPA) | |
| | Native) | | | |
| +-------+--------+ +-------+--------+ |
| | | |
| | HTTPS/JSON | HTTPS/JSON |
| | | |
| +-------------+-------------+ |
| | |
| v |
| +---------+---------+ |
| | API Gateway | |
| | [Container] | |
| | (Kong) | |
| +---------+---------+ |
| | |
| +-------------+-------------+-------------+ |
| | | | | |
| v v v v |
| +-------+----+ +------+-----+ +-----+------+ +----+-------+ |
| | Order | | Delivery | | Restaurant | | User | |
| | Service | | Service | | Service | | Service | |
| | [Container]| | [Container]| | [Container]| | [Container]| |
| | (Node.js) | | (Go) | | (Node.js) | | (Node.js) | |
| +-----+------+ +-----+------+ +-----+------+ +-----+------+ |
| | | | | |
| | | | | |
| +-----+--------+------+-------+-------+------+ |
| | | | |
| v v v |
| +-------+-------+ +-----+-----+ +-------+-------+ |
| | PostgreSQL | | Redis | | Message Queue | |
| | [Container] | | Cache | | [Container] | |
| | (Primary DB) | | [Container]| | (RabbitMQ) | |
| +---------------+ +-----------+ +---------------+ |
| |
+------------------------------------------------------------------------+
ARROWS KEY:
────────> Synchronous (REST/gRPC)
- - - - > Asynchronous (Message Queue)
The Core Question You’re Answering
“What are the major technical building blocks and how do they communicate?”
Concepts You Must Understand First
- What is a container in C4? A separately deployable unit (not Docker containers specifically).
- What is an API Gateway? A single entry point that routes to backend services.
- What is the difference between sync and async communication? Blocking vs non-blocking.
Questions to Guide Your Design
- What applications do users interact with?
- What backend services exist?
- What databases and caches are used?
- What message queues enable async processing?
- What protocols connect containers? (HTTP, gRPC, AMQP)
The Interview Questions They’ll Ask
- “Why separate services instead of a monolith?”
- Independent deployment
- Technology flexibility
- Team autonomy
- Targeted scaling
- “How do you decide when to add a message queue?”
- When operations can be async
- When you need to decouple services
- When you need to buffer load spikes
- “What’s the difference between C4 containers and Docker containers?”
- C4 container: Logical deployable unit
- Docker container: Specific packaging technology
- One C4 container might use multiple Docker containers
- “How detailed should technology annotations be?”
- Enough to understand major decisions: “(Node.js)”, “(PostgreSQL)”
- Not implementation details: versions, libraries
Project 7: C4 Component Diagram
| Attribute | Value |
|---|---|
| Difficulty | Intermediate |
| Time Estimate | 2 days |
| Tools | Structurizr, draw.io |
| Key Concept | Code organization |
What you’ll build: A C4 Component diagram zooming into the Order Service container, showing: OrderController, OrderService, OrderRepository, PaymentClient, NotificationClient, and their dependencies.
Why it teaches diagramming: Component diagrams show how code is organized. This is the bridge between architecture and implementation.
Core challenges you’ll face:
- Identifying components: Logical groupings, not every class
- Showing dependencies: Which components call which?
- Mapping to containers: How components use external services
- Avoiding class-diagram level: Stay at module/package level
Real World Outcome
+------------------------------------------------------------------------+
| Order Service [Container] |
| (Node.js) |
+------------------------------------------------------------------------+
| |
| +--------------------+ |
| | OrderController | <-- REST endpoints |
| | [Component] | |
| | Handles HTTP | |
| | requests | |
| +---------+----------+ |
| | |
| | Uses |
| v |
| +---------+----------+ |
| | OrderService | <-- Business logic |
| | [Component] | |
| | Creates, updates, | |
| | cancels orders | |
| +---------+----------+ |
| | |
| +---------+---------+---------+---------+ |
| | | | | | |
| v v v v v |
| +-+-+ +-----+---+ +---+---+ +---+-----+ +-+-------+ |
| | | |Order | |Payment| |Notific- | |Delivery | |
| | | |Repo | |Client | |ation | |Client | |
| | V | |[Comp] | |[Comp] | |Client | |[Comp] | |
| | a | | | | | |[Comp] | | | |
| | l | |Persists | |Calls | | | |Calls | |
| | i | |orders | |payment| |Sends | |delivery | |
| | d | |to DB | |gateway| |emails/ | |service | |
| | a | | | | | |SMS | | | |
| | t | +-+-------+ +---+---+ +---+-----+ +----+----+ |
| | o | | | | | |
| | r | | | | | |
| +---+ | | | | |
| | | | | |
+---------|-------------|---------|------------|---------------------------+
| | | |
v v v v
+-----+-----+ +-----+----+ +--+----+ +-----+------+
| PostgreSQL| | Payment | | Email | | Delivery |
| [Ext] | | Gateway | | Service| | Service |
| | | [Ext] | | [Ext] | | [Container]|
+-----------+ +----------+ +-------+ +------------+
The Core Question You’re Answering
“How is this container organized internally, and what are its responsibilities?”
The Interview Questions They’ll Ask
- “At what granularity should components be defined?”
- Logical groupings that serve a coherent purpose
- Not individual classes, not whole services
- “How do you identify component boundaries?”
- Single responsibility
- Cohesive functionality
- Clear interface to other components
- “When is a component diagram too detailed?”
- When it shows every class
- When arrows become unreadable
- When business logic appears
Project 8: Deployment Diagram
| Attribute | Value |
|---|---|
| Difficulty | Intermediate |
| Time Estimate | 2 days |
| Tools | draw.io, Lucidchart, PlantUML |
| Key Concept | Infrastructure mapping |
What you’ll build: A deployment diagram showing how the food delivery system maps to AWS infrastructure: EKS cluster, RDS, ElastiCache, SQS, with load balancers and availability zones.
Why it teaches diagramming: Deployment diagrams answer: “Where does this run?” This is critical for operations, scaling, and cost discussions.
Core challenges you’ll face:
- Nodes and artifacts: Physical/virtual machines vs software
- Showing redundancy: Multiple availability zones
- Cloud provider specifics: AWS icons vs generic boxes
- Network boundaries: VPCs, subnets, security groups
Real World Outcome
+------------------------------------------------------------------------+
| AWS Cloud |
+------------------------------------------------------------------------+
| |
| +---------------------------+ +---------------------------+ |
| | Availability Zone A | | Availability Zone B | |
| +---------------------------+ +---------------------------+ |
| | | | | |
| | +-----------------+ | | +-----------------+ | |
| | | EKS Node Pool | | | | EKS Node Pool | | |
| | | [EC2 Instances]| | | | [EC2 Instances]| | |
| | | | | | | | | |
| | | +-------------+ | | | | +-------------+ | | |
| | | |Order Service| | | | | |Order Service| | | |
| | | | [Pod] | | | | | | [Pod] | | | |
| | | +-------------+ | | | | +-------------+ | | |
| | | +-------------+ | | | | +-------------+ | | |
| | | |Delivery Svc | | | | | |Delivery Svc | | | |
| | | | [Pod] | | | | | | [Pod] | | | |
| | | +-------------+ | | | | +-------------+ | | |
| | +-----------------+ | | +-----------------+ | |
| | ^ | | ^ | |
| | | | | | | |
| +-----------|---------------+ +--------------|------------+ |
| | | |
| +----------------+-----------------+ |
| | |
| +-----------v-----------+ |
| | Application Load | |
| | Balancer | |
| | [ALB] | |
| +-----------+-----------+ |
| ^ |
| | |
| +---------------------------+---------------------------+ |
| | | | |
| v v v |
| +--+-------+ +-------+------+ +--------+------+ |
| | CloudFront| | Route 53 | | WAF | |
| | [CDN] | | [DNS] | | [Firewall] | |
| +-----------+ +--------------+ +---------------+ |
| |
| +------------------------------------------------------------------+ |
| | Data Layer | |
| +------------------------------------------------------------------+ |
| | | |
| | +----------------+ +----------------+ +----------------+ | |
| | | RDS | | ElastiCache | | SQS | | |
| | | PostgreSQL | | Redis | | Message Queue | | |
| | | [Multi-AZ] | | [Cluster] | | | | |
| | +----------------+ +----------------+ +----------------+ | |
| | | |
| +------------------------------------------------------------------+ |
| |
+------------------------------------------------------------------------+
The Core Question You’re Answering
“How does the logical architecture map to physical infrastructure?”
The Interview Questions They’ll Ask
- “How do you show high availability?”
- Multiple instances across availability zones
- Load balancers distributing traffic
- Database replication (Multi-AZ)
- “When do you use cloud provider icons vs generic boxes?”
- Provider icons: Implementation-specific diagrams
- Generic: When portability matters or early design
- “What’s the difference between a deployment and a container diagram?”
- Container: What software runs (logical)
- Deployment: Where software runs (physical/virtual)
Project 9: Mermaid.js for Docs-as-Code
| Attribute | Value |
|---|---|
| Difficulty | Beginner |
| Time Estimate | 1-2 days |
| Tools | Mermaid Live Editor, GitHub, VS Code |
| Key Concept | Embedded diagrams |
What you’ll build: A technical design document with embedded Mermaid diagrams that render in GitHub, GitLab, Notion, and documentation sites. Include a class diagram, sequence diagram, and flowchart.
Why it teaches diagramming: Mermaid is the most accessible diagram-as-code tool. It renders natively in GitHub, requires no installation, and uses simple syntax.
Core challenges you’ll face:
- Syntax quirks: Different diagram types have different rules
- Layout control: Mermaid auto-layouts, sometimes suboptimally
- Theme customization: Matching documentation style
- Complex diagrams: When Mermaid struggles vs shines
Real World Outcome
A markdown file with rendered diagrams:
# Payment Processing Design
## System Overview
\`\`\`mermaid
graph TB
subgraph Client
A[Mobile App] --> B[API Gateway]
end
subgraph Backend
B --> C[Payment Service]
C --> D[(Database)]
C --> E[Stripe API]
end
\`\`\`
## Payment Flow
\`\`\`mermaid
sequenceDiagram
participant U as User
participant A as App
participant P as Payment Service
participant S as Stripe
U->>A: Submit Payment
A->>P: Create PaymentIntent
P->>S: Create PaymentIntent
S-->>P: PaymentIntent ID
P-->>A: Client Secret
A->>S: Confirm Payment (client-side)
S-->>A: Payment Result
A->>P: Webhook: payment_succeeded
P->>P: Update Order Status
P-->>A: Confirmation
A-->>U: Success Screen
\`\`\`
## State Machine
\`\`\`mermaid
stateDiagram-v2
[*] --> Pending
Pending --> Processing : submit
Processing --> Completed : success
Processing --> Failed : error
Failed --> Pending : retry
Completed --> Refunded : refund
Refunded --> [*]
Failed --> [*] : abandon
\`\`\`
The Core Question You’re Answering
“How do I embed diagrams in documentation that stay in sync with the code?”
Concepts You Must Understand First
- What is docs-as-code? Treating documentation like source code: version controlled, reviewed, tested.
- What is Mermaid? A JavaScript library that renders diagrams from text.
- Where does Mermaid render natively? GitHub, GitLab, Notion, Obsidian, many static site generators.
The Interview Questions They’ll Ask
- “Why use Mermaid over a visual tool?”
- Version control (git diff shows changes)
- Code review (diagram changes in PRs)
- No special tools needed (renders in browser)
- Stays with the code
- “What are Mermaid’s limitations?”
- Limited layout control
- Complex diagrams become unreadable
- Some diagram types not supported
- Styling can be tricky
- “How do you handle Mermaid diagrams that get too complex?”
- Split into multiple smaller diagrams
- Use a more powerful tool (D2, PlantUML)
- Export and embed as images
Hints in Layers
Hint 1: Start at https://mermaid.live - instant preview.
Hint 2: Common diagram types:
graph TB(flowchart top-bottom)sequenceDiagramclassDiagramstateDiagram-v2erDiagramgantt
Hint 3: Test rendering in your target platform (GitHub/GitLab differ slightly).
Hint 4: For complex styling, use %%{init: {'theme': 'dark'}}%% at diagram start.
Books That Will Help
| Topic | Book & Chapter |
|---|---|
| Docs as code | “Docs as Code” by Anne Gentle |
| Mermaid syntax | Mermaid Official Documentation |
| Technical writing | “The Documentation System” by Divio |
Project 10: PlantUML for Enterprise Diagrams
| Attribute | Value |
|---|---|
| Difficulty | Intermediate |
| Time Estimate | 2-3 days |
| Tools | PlantUML, VS Code extension, Docker |
| Key Concept | Comprehensive UML tooling |
What you’ll build: A complete system design document using PlantUML: use case diagram, class diagram with stereotypes, sequence diagram with alt/loop, component diagram, and deployment diagram.
Why it teaches diagramming: PlantUML is the industry standard for text-based UML. It supports every UML diagram type and has excellent IDE integration.
Core challenges you’ll face:
- Graphviz dependency: Layout engine installation
- Syntax verbosity: More explicit than Mermaid
- Enterprise notation: Stereotypes, packages, notes
- CI/CD integration: Generating images in pipelines
Real World Outcome
Multiple .puml files with generated images:
@startuml
!theme cerulean
title Order Management System - Use Cases
left to right direction
actor Customer as C
actor "Restaurant Staff" as RS
actor "Delivery Driver" as DD
actor Admin as A
rectangle "Order System" {
usecase "Browse Menu" as UC1
usecase "Place Order" as UC2
usecase "Track Delivery" as UC3
usecase "Process Payment" as UC4
usecase "Manage Menu" as UC5
usecase "Accept Order" as UC6
usecase "Update Status" as UC7
usecase "View Analytics" as UC8
}
C --> UC1
C --> UC2
C --> UC3
UC2 ..> UC4 : <<include>>
RS --> UC5
RS --> UC6
DD --> UC7
A --> UC8
@enduml
@startuml
title Order Service - Class Diagram
package "Domain" {
class Order {
- id: UUID
- status: OrderStatus
- createdAt: DateTime
- items: List<OrderItem>
+ addItem(item: OrderItem)
+ calculateTotal(): Money
+ cancel(): void
}
class OrderItem {
- productId: UUID
- quantity: int
- price: Money
}
enum OrderStatus {
PENDING
CONFIRMED
PREPARING
READY
DELIVERED
CANCELLED
}
Order "1" *-- "*" OrderItem
Order --> OrderStatus
}
package "Application" {
interface OrderRepository <<interface>> {
+ save(order: Order): void
+ findById(id: UUID): Order
}
class OrderService {
- repository: OrderRepository
+ createOrder(dto: CreateOrderDTO): Order
+ cancelOrder(id: UUID): void
}
OrderService --> OrderRepository
}
package "Infrastructure" {
class PostgresOrderRepository {
- dataSource: DataSource
}
PostgresOrderRepository ..|> OrderRepository
}
@enduml
The Core Question You’re Answering
“How do I create comprehensive UML documentation that integrates with enterprise workflows?”
The Interview Questions They’ll Ask
- “Why PlantUML over Mermaid?”
- More UML diagram types
- Better layout for complex diagrams
- Stereotypes and enterprise notation
- Sprite/icon libraries
- “How do you integrate PlantUML in CI/CD?”
# Using Docker docker run -v $(pwd):/data plantuml/plantuml diagrams/*.puml # Output PNGs to docs/ java -jar plantuml.jar -o ../docs diagrams/*.puml - “What is a stereotype in PlantUML?”
- Annotates elements with semantic meaning
<<interface>>,<<abstract>>,<<service>>
Hints in Layers
Hint 1: Use VS Code with “PlantUML” extension for live preview.
Hint 2: Start each diagram with @startuml and end with @enduml.
Hint 3: Use !include to share common definitions:
!include common/skin.puml
!include common/icons.puml
Hint 4: For sequence diagrams with conditionals:
alt success
A -> B: Request
B --> A: 200 OK
else failure
B --> A: 500 Error
end
Project 11: Diagrams-as-Code with Python
| Attribute | Value |
|---|---|
| Difficulty | Intermediate |
| Time Estimate | 2-3 days |
| Tools | Python diagrams library |
| Key Concept | Programmatic diagram generation |
What you’ll build: A Python script that generates AWS architecture diagrams programmatically. Show dynamic diagram generation based on infrastructure-as-code files (reading from Terraform state or Kubernetes manifests).
Why it teaches diagramming: Sometimes you need to generate diagrams from data, not write them manually. This is essential for keeping documentation in sync with infrastructure.
Core challenges you’ll face:
- Cloud provider icons: AWS, GCP, Azure, K8s
- Programmatic layout: Clusters, groupings
- Data-driven generation: Reading from config files
- Output formats: PNG, PDF, DOT
Real World Outcome
A Python script that produces:
from diagrams import Diagram, Cluster, Edge
from diagrams.aws.compute import EKS, EC2
from diagrams.aws.database import RDS, ElastiCache
from diagrams.aws.network import ALB, CloudFront, Route53
from diagrams.aws.integration import SQS
from diagrams.aws.security import WAF
with Diagram("Food Delivery Platform", show=False, direction="TB"):
dns = Route53("Route 53")
cdn = CloudFront("CloudFront")
waf = WAF("WAF")
with Cluster("VPC"):
lb = ALB("Application\nLoad Balancer")
with Cluster("EKS Cluster"):
with Cluster("AZ-A"):
svc_a = [
EKS("Order Service"),
EKS("Delivery Service")
]
with Cluster("AZ-B"):
svc_b = [
EKS("Order Service"),
EKS("Delivery Service")
]
with Cluster("Data Layer"):
db = RDS("PostgreSQL\nMulti-AZ")
cache = ElastiCache("Redis Cluster")
queue = SQS("Order Queue")
dns >> cdn >> waf >> lb
lb >> svc_a
lb >> svc_b
svc_a >> db
svc_a >> cache
svc_a >> queue
svc_b >> db
svc_b >> cache
svc_b >> queue
The Core Question You’re Answering
“How do I generate architecture diagrams programmatically from infrastructure data?”
The Interview Questions They’ll Ask
- “When would you use programmatic diagram generation?”
- Large, frequently changing infrastructure
- Multiple environments (dev, staging, prod)
- Compliance/audit requirements for current-state documentation
- Generating diagrams from IaC (Terraform, CloudFormation)
- “How do you keep diagrams in sync with infrastructure?”
- CI/CD job that regenerates diagrams on merge
- Read from Terraform state files
- Parse Kubernetes manifests
- Query cloud provider APIs
- “What cloud providers does the diagrams library support?”
- AWS, GCP, Azure, Alibaba Cloud
- Kubernetes, On-premise
- Programming languages, frameworks
- SaaS products
Hints in Layers
Hint 1: Install with pip install diagrams. Requires Graphviz.
Hint 2: Use Cluster for visual groupings.
Hint 3: Edge direction matters: a >> b means a flows to b.
Hint 4: Read Terraform state:
import json
import subprocess
# Get Terraform state
result = subprocess.run(
["terraform", "show", "-json"],
capture_output=True,
cwd="./infrastructure"
)
state = json.loads(result.stdout)
# Extract resources and generate diagram
for resource in state["values"]["root_module"]["resources"]:
if resource["type"] == "aws_instance":
# Add EC2 node to diagram
pass
Project 12: D2 Language Modern Diagrams
| Attribute | Value |
|---|---|
| Difficulty | Intermediate |
| Time Estimate | 2 days |
| Tools | D2 CLI, VS Code extension |
| Key Concept | Modern diagram syntax |
What you’ll build: A complete system architecture using D2, showcasing its unique features: markdown in nodes, code blocks, SQL tables, icons, and themes.
Why it teaches diagramming: D2 is a modern alternative to PlantUML with a cleaner syntax, better defaults, and unique features like markdown content and SQL schema rendering.
Core challenges you’ll face:
- Declarative syntax: Different from procedural PlantUML
- Connection labels: Inline vs block style
- Nested containers: Scoping with curly braces
- Theme customization: TALA layouts
Real World Outcome
A D2 file with rich content:
direction: right
title: |md
# E-Commerce System
Architecture overview with service boundaries
|
user: {
label: Customer
icon: https://icons.terrastruct.com/essentials/002-user.svg
shape: person
}
frontend: {
label: Web Application
description: |md
## React SPA
- TypeScript
- Redux Toolkit
- React Query
|
components: {
ProductList
Cart
Checkout
}
}
backend: {
label: Backend Services
api-gateway: API Gateway {
shape: hexagon
style.fill: "#f0f0f0"
}
services: {
product-svc: Product Service
order-svc: Order Service
user-svc: User Service
product-svc -> db.products
order-svc -> db.orders
user-svc -> db.users
}
api-gateway -> services
}
db: {
label: PostgreSQL
shape: cylinder
products: |sql
CREATE TABLE products (
id UUID PRIMARY KEY,
name VARCHAR(255),
price DECIMAL(10,2),
stock INT
);
|
orders: |sql
CREATE TABLE orders (
id UUID PRIMARY KEY,
user_id UUID REFERENCES users(id),
status VARCHAR(50),
total DECIMAL(10,2)
);
|
users: |sql
CREATE TABLE users (
id UUID PRIMARY KEY,
email VARCHAR(255) UNIQUE,
password_hash VARCHAR(255)
);
|
}
user -> frontend: Browse & Purchase
frontend -> backend.api-gateway: REST/GraphQL {
style.stroke-dash: 5
}
backend.services -> external: {
style.stroke: red
}
external: {
label: External Services
stripe: Stripe
sendgrid: SendGrid
}
The Core Question You’re Answering
“How do I create modern, readable diagrams with rich content like code blocks and markdown?”
The Interview Questions They’ll Ask
- “What makes D2 different from PlantUML?”
- Cleaner, more readable syntax
- Native markdown and code block support
- Better default layouts (TALA engine)
- SQL schema visualization
- More intuitive nesting
- “When would you choose D2 over Mermaid?”
- Complex diagrams that need better layout
- Documentation-heavy diagrams (markdown)
- SQL schema documentation
- When you want code blocks in diagrams
- “What output formats does D2 support?”
- SVG (default)
- PNG
- GIF (animated)
Hints in Layers
Hint 1: Install: brew install d2 or curl -fsSL https://d2lang.com/install.sh | sh
Hint 2: Basic syntax:
a -> b: connection label
a: {
shape: rectangle
nested -> thing
}
Hint 3: Use |md ... | for markdown content, |sql ... | for SQL.
Hint 4: Watch mode for live preview: d2 --watch input.d2 output.svg
Project 13: ASCII Diagrams for Documentation
| Attribute | Value |
|---|---|
| Difficulty | Beginner |
| Time Estimate | 1-2 days |
| Tools | Monodraw, ASCIIFlow, Vim/Emacs |
| Key Concept | Universal compatibility |
What you’ll build: A library of ASCII diagram templates for common patterns: sequence flows, architecture boxes, state machines, and data structures. Store them as code comments and terminal-friendly READMEs.
Why it teaches diagramming: ASCII diagrams are the most portable format. They work in code comments, terminal output, emails, and any text editor. They never break.
Core challenges you’ll face:
- Character alignment: Getting boxes to line up
- Arrow styles: Different meanings for ->, –>, ==>
- Monospace fonts: Ensuring consistent rendering
- Tool selection: Drawing vs typing
Real World Outcome
A collection of reusable templates:
# Architecture Box Template
+-------------------+ +-------------------+ +-------------------+
| | | | | |
| Component A +----->+ Component B +----->+ Component C |
| | | | | |
+-------------------+ +-------------------+ +-------------------+
| | |
| | |
v v v
+-------+-------+ +-------+-------+ +-------+-------+
| | | | | |
| Database A | | Database B | | Database C |
| | | | | |
+---------------+ +---------------+ +---------------+
# Sequence Flow Template
Client Server Database
| | |
| 1. Request | |
+--------------------->| |
| | 2. Query |
| +--------------------->|
| | |
| | 3. Results |
| |<---------------------+
| 4. Response | |
|<---------------------+ |
| | |
# State Machine Template
+----------+
| START |
+----+-----+
|
v
+-------+--------+
| |
+---->| STATE A |
| | |
| +-------+--------+
| |
| event | [guard]
| v
| +-------+--------+
| | |
+-----+ STATE B |
| |
+-------+--------+
|
v
+----+-----+
| END |
+----------+
# Tree Structure Template
.
├── src/
│ ├── components/
│ │ ├── Header.tsx
│ │ ├── Footer.tsx
│ │ └── Nav.tsx
│ ├── pages/
│ │ ├── Home.tsx
│ │ └── About.tsx
│ └── utils/
│ └── helpers.ts
├── tests/
│ └── components/
│ └── Header.test.tsx
└── package.json
# Memory Layout Template
+------------------+ 0x0000
| |
| Stack | <- grows down
| | |
| v |
+------------------+
| |
| (free) |
| |
+------------------+
| ^ |
| | |
| Heap | <- grows up
| |
+------------------+
| |
| Data Segment |
| |
+------------------+
| |
| Code Segment |
| |
+------------------+ 0xFFFF
The Core Question You’re Answering
“How do I create diagrams that work everywhere, including code comments and terminals?”
The Interview Questions They’ll Ask
- “When would you use ASCII over graphical diagrams?”
- Code comments (explain complex logic inline)
- READMEs that must work on any terminal
- Email/chat when pasting images is awkward
- Legacy systems without graphics support
- “What tools help create ASCII diagrams?”
- ASCIIFlow (web-based drawing)
- Monodraw (macOS native)
- Vim/Emacs with draw modes
- Graph::Easy (text to ASCII)
- “How do you handle ASCII diagrams in version control?”
- They diff beautifully (just text)
- Changes are obvious in PRs
- No binary files in repo
Hints in Layers
Hint 1: Use https://asciiflow.com for quick web-based drawing.
Hint 2: Standard box characters: +, -, |, >, v, ^
Hint 3: For code comments, use 80-character width max.
Hint 4: Store templates in a team wiki or shared repo.
Project 14: Architecture Decision Records (ADRs)
| Attribute | Value |
|---|---|
| Difficulty | Intermediate |
| Time Estimate | 2-3 days |
| Tools | Markdown, adr-tools, Log4brains |
| Key Concept | Decision documentation |
What you’ll build: An ADR repository documenting 5 significant architecture decisions for a project, complete with context, options considered, consequences, and visual diagrams showing the chosen approach.
Why it teaches diagramming: ADRs combine narrative with visuals to capture “why” not just “what.” The diagrams in ADRs show alternatives considered and trade-offs made.
Core challenges you’ll face:
- Writing context: Capturing the situation at decision time
- Showing alternatives: Diagramming options NOT chosen
- Consequences: Being honest about trade-offs
- Maintaining ADRs: Superseding outdated decisions
Real World Outcome
ADR directory structure:
docs/adr/
├── 0001-record-architecture-decisions.md
├── 0002-use-postgresql-for-primary-database.md
├── 0003-adopt-event-driven-architecture.md
├── 0004-implement-api-gateway-pattern.md
├── 0005-use-kubernetes-for-container-orchestration.md
└── README.md
Example ADR:
# 3. Adopt Event-Driven Architecture
Date: 2024-01-15
## Status
Accepted
## Context
Our order processing system requires:
- Real-time updates to multiple downstream services
- Resilience to temporary service failures
- Ability to replay events for debugging and analytics
- Decoupling between order creation and fulfillment
Current synchronous architecture creates tight coupling:
\`\`\`
+--------+ +--------+ +--------+ +--------+
| Order |---->|Inventory|---->|Shipping|---->|Billing |
| Service| | Service | | Service| | Service|
+--------+ +--------+ +--------+ +--------+
Problem: If Shipping is down, entire order fails.
Problem: Adding new downstream service requires Order Service changes.
\`\`\`
## Decision
We will adopt an event-driven architecture using Apache Kafka.
\`\`\`
+--------+ +-------+ +--------+
| Order |---->| Kafka |<----| Inventory |
| Service| | Topic | | Service |
+--------+ +---+---+ +-----------+
|
+---------+---------+
| | |
v v v
+--------+ +--------+ +--------+
|Shipping| |Billing | |Analytics|
| Service| | Service| | Service |
+--------+ +--------+ +--------+
Benefits:
- Services are decoupled
- Events can be replayed
- New consumers added without producer changes
\`\`\`
## Consequences
### Positive
- **Resilience**: If Shipping is down, events queue. No data loss.
- **Scalability**: Each service scales independently.
- **Extensibility**: Add Analytics without touching Order Service.
### Negative
- **Complexity**: Eventual consistency model is harder to reason about.
- **Operations**: Kafka cluster requires expertise to operate.
- **Debugging**: Distributed tracing now required.
### Neutral
- Team must learn event sourcing patterns.
- Need to implement idempotent consumers.
## Options Considered
### Option 1: Keep Synchronous (Rejected)
- Pros: Simple, familiar
- Cons: Does not solve coupling problem
### Option 2: AWS SNS/SQS (Rejected)
- Pros: Managed service, AWS native
- Cons: No event replay, vendor lock-in
### Option 3: RabbitMQ (Rejected)
- Pros: Simpler than Kafka
- Cons: No log persistence, harder to scale
## References
- [Martin Fowler: Event-Driven Architecture](https://martinfowler.com/articles/201701-event-driven.html)
- [Designing Data-Intensive Applications, Ch. 11](https://dataintensive.net/)
The Core Question You’re Answering
“How do I document architectural decisions so future developers understand WHY we built it this way?”
The Interview Questions They’ll Ask
- “What’s the difference between an ADR and a design document?”
- ADR: Captures a single decision with context and consequences
- Design doc: Comprehensive plan for a feature or system
- ADRs are immutable; design docs evolve
- “When should you write an ADR?”
- Any decision that affects structure
- Any decision that’s controversial
- Any decision future devs will question
- “How do you handle superseded ADRs?”
- Never delete. Mark as “Superseded by ADR-00X”
- The history of decisions is valuable
- “What makes a good ADR?”
- Context that captures the constraints at the time
- Alternatives that were actually considered
- Honest consequences (positive AND negative)
Hints in Layers
Hint 1: Use adr-tools for templating: adr new Use PostgreSQL for primary database
Hint 2: Always include at least one diagram showing the decision.
Hint 3: Write ADRs at decision time, not after the fact.
Hint 4: Include links to related ADRs: “See also ADR-005 for…”
Books That Will Help
| Topic | Book & Chapter |
|---|---|
| ADR format | “Design It!” by Michael Keeling - Ch. 13 |
| Decision making | “Fundamentals of Software Architecture” - Ch. 19 |
| Trade-off analysis | “Software Architecture: The Hard Parts” - Ch. 2 |
Project 15: API Documentation with Visuals
| Attribute | Value |
|---|---|
| Difficulty | Intermediate |
| Time Estimate | 2-3 days |
| Tools | OpenAPI, Swagger UI, Redoc, Mermaid |
| Key Concept | Developer experience |
What you’ll build: API documentation that includes sequence diagrams for complex flows, entity relationship diagrams for request/response schemas, and state diagrams for resource lifecycles.
Why it teaches diagramming: Good API docs don’t just list endpoints. They show how endpoints work together, what data structures are involved, and how resource states change.
Core challenges you’ll face:
- Integrating diagrams with OpenAPI: Where do visuals go?
- Flow documentation: Multi-step API workflows
- Schema visualization: Complex nested objects
- Versioning diagrams: Keeping sync with API changes
Real World Outcome
Enhanced API documentation:
# openapi.yaml
openapi: 3.0.3
info:
title: Order API
version: 1.0.0
description: |
## Overview
The Order API allows you to create, manage, and fulfill orders.
## Authentication
All endpoints require Bearer token authentication.
## Order Lifecycle
```mermaid
stateDiagram-v2
[*] --> PENDING: POST /orders
PENDING --> CONFIRMED: POST /orders/{id}/confirm
CONFIRMED --> PROCESSING: PUT /orders/{id}/status
PROCESSING --> SHIPPED: PUT /orders/{id}/status
SHIPPED --> DELIVERED: PUT /orders/{id}/status
PENDING --> CANCELLED: DELETE /orders/{id}
CONFIRMED --> CANCELLED: DELETE /orders/{id}
DELIVERED --> [*]
CANCELLED --> [*]
```
## Common Flows
### Create and Fulfill Order
```mermaid
sequenceDiagram
participant C as Client
participant A as Order API
participant I as Inventory
participant P as Payment
C->>A: POST /orders
A->>I: Check stock
I-->>A: Stock available
A-->>C: 201 Created (PENDING)
C->>A: POST /orders/{id}/confirm
A->>P: Process payment
P-->>A: Payment success
A-->>C: 200 OK (CONFIRMED)
```
paths:
/orders:
post:
summary: Create a new order
description: |
Creates a new order in PENDING status.
## Request Flow
```mermaid
sequenceDiagram
Client->>API: POST /orders
API->>API: Validate items
API->>Inventory: Reserve stock
Inventory-->>API: Reservation ID
API->>DB: Save order
API-->>Client: Order created
```
The Core Question You’re Answering
“How do I help developers understand not just what endpoints exist, but how to use them together?”
The Interview Questions They’ll Ask
- “Where do diagrams fit in OpenAPI documentation?”
- Info description (overview diagrams)
- Operation descriptions (flow diagrams)
- Schema descriptions (entity relationships)
- External docs for complex flows
- “How do you keep API diagrams in sync?”
- Generate diagrams from OpenAPI spec when possible
- Include diagrams in API review process
- Version diagrams with API versions
- “What diagrams are most useful for API docs?”
- Sequence diagrams: Multi-step flows
- State diagrams: Resource lifecycles
- ER diagrams: Schema relationships
Project 16: System Context Diagrams
| Attribute | Value |
|---|---|
| Difficulty | Beginner |
| Time Estimate | 1-2 days |
| Tools | Excalidraw, draw.io, C4-PlantUML |
| Key Concept | Scope definition |
What you’ll build: System context diagrams for three different systems: a SaaS product, an internal enterprise tool, and an IoT platform. Each shows clear boundaries and integrations.
Why it teaches diagramming: Context diagrams are the most valuable single diagram. They define scope, identify stakeholders, and show dependencies at a glance.
Core challenges you’ll face:
- Scope decisions: What is “in” vs “out”?
- Actor identification: All human and system users
- Integration clarity: External dependencies
- Labeling: Meaningful relationship descriptions
Real World Outcome
Three distinct context diagrams:
# SaaS Product: Project Management Tool
+----------------+ +----------------+
| End Users | | Administrators |
| [Person] | | [Person] |
| Create tasks, | | Configure org, |
| track progress | | manage users |
+-------+--------+ +--------+-------+
| |
| Creates and manages |
| projects |
| |
v v
+-------+-----------------------------------------------------+-------+
| |
| Project Management Platform |
| [Software System] |
| |
| Enables teams to plan, track, and deliver projects |
| |
+---+------------+------------+------------+------------+-------------+
| | | | |
| | | | |
v v v v v
+---+---+ +----+---+ +----+----+ +----+----+ +---+----+
| SSO | | Email | | Slack | | GitHub | | S3 |
| IdP | | Service| | API | | API | | Storage|
| [Ext] | | [Ext] | | [Ext] | | [Ext] | | [Ext] |
+-------+ +--------+ +---------+ +---------+ +--------+
Authenticates Sends Posts Syncs Stores
users notifications updates commits files
# Enterprise Tool: HR Management System
+---------------+ +---------------+ +---------------+
| Employees | | HR Staff | | Managers |
| [Person] | | [Person] | | [Person] |
| Submit PTO, | | Process | | Approve |
| view payslips | | payroll | | requests |
+-------+-------+ +-------+-------+ +-------+-------+
| | |
+--------------------+--------------------+
|
v
+------------------+------------------+
| |
| HR Management System |
| [Software System] |
| |
| Manages employee data, payroll, |
| and HR processes |
| |
+--+-------------+-------------+------+
| | |
v v v
+-----+----+ +-----+----+ +-----+----+
| Payroll | | Benefits | | Active |
| Provider | | Platform | | Directory|
| [Ext] | | [Ext] | | [Ext] |
+----------+ +----------+ +----------+
Processes Manages Syncs user
payments 401k, health accounts
The Core Question You’re Answering
“What is the boundary of this system and what does it interact with?”
The Interview Questions They’ll Ask
- “How do you determine system boundaries?”
- What code do you own?
- What can you deploy independently?
- What teams are responsible?
- “How detailed should context diagrams be?”
- Keep to 5-15 elements
- Show major actors and systems
- Use relationship labels
- “When do you update a context diagram?”
- New integration added
- User type added
- System scope changes
Project 17: Threat Modeling Diagrams
| Attribute | Value |
|---|---|
| Difficulty | Advanced |
| Time Estimate | 3-4 days |
| Tools | Microsoft Threat Modeling Tool, OWASP Threat Dragon, draw.io |
| Key Concept | Security visualization |
What you’ll build: A complete threat model for a payment processing system, including data flow diagrams (DFDs) with trust boundaries, STRIDE threat identification, and mitigation mapping.
Why it teaches diagramming: Threat modeling diagrams are specialized data flow diagrams that reveal attack surfaces. They are essential for secure design reviews and compliance.
Core challenges you’ll face:
- Trust boundaries: Where do trust levels change?
- Data flow identification: All paths data takes
- STRIDE application: Spoofing, Tampering, Repudiation, Information Disclosure, DoS, Elevation of Privilege
- Threat enumeration: Systematic threat identification
Real World Outcome
A threat modeling document with diagrams:
# Payment Processing System - Threat Model
## Level 0: Context Diagram
+------------------------------------------------------------------+
| |
| +----------+ +-------------------+ +-------+ |
| | Customer |--------->| Payment System |--------->| Bank | |
| | [Person] | | [Trust Zone 1] | | [Ext] | |
| +----------+ +-------------------+ +-------+ |
| |
+------------------------------------------------------------------+
## Level 1: Data Flow Diagram with Trust Boundaries
+=======================================================================+
|| TRUST BOUNDARY: INTERNET ||
+=======================================================================+
| |
| +----------+ |
| | Customer | |
| | Browser | |
| +----+-----+ |
| | |
| | (1) Card Details [HTTPS] |
| v |
|========|==============================================================|
|| v TRUST BOUNDARY: DMZ ||
|========|==============================================================|
| | |
| +----v-------+ |
| | WAF/LB | |
| +----+-------+ |
| | |
| | (2) Sanitized Request |
| v |
|========|==============================================================|
|| v TRUST BOUNDARY: APPLICATION ||
|========|==============================================================|
| | |
| +----v-----------+ +-------------------+ |
| | Payment API |---(3)--->| Card Vault | |
| | [Process 1] | | [Data Store] | |
| +----+-----------+ | (Encrypted PAN) | |
| | +-------------------+ |
| | |
| | (4) Tokenized Card |
| v |
|========|==============================================================|
|| v TRUST BOUNDARY: BACKEND ||
|========|==============================================================|
| | |
| +----v-----------+ +-------------------+ |
| | Payment |---(5)--->| Transaction | |
| | Processor | | Database | |
| | [Process 2] | | [Data Store] | |
| +----+-----------+ +-------------------+ |
| | |
| | (6) Payment Request |
| v |
|========|==============================================================|
|| v TRUST BOUNDARY: EXTERNAL ||
|========|==============================================================|
| | |
| +----v-----------+ |
| | Bank Gateway | |
| | [External] | |
| +----------------+ |
| |
+------------------------------------------------------------------------+
## STRIDE Threat Analysis
| Element | Threat Type | Threat | Mitigation |
|---------|-------------|--------|------------|
| (1) Card Details | Spoofing | Attacker impersonates customer | MFA, device fingerprinting |
| (1) Card Details | Info Disclosure | Man-in-middle | TLS 1.3, certificate pinning |
| (2) WAF | Tampering | SQL injection | Input validation, parameterized queries |
| (3) Card Vault | Info Disclosure | Data breach | Encryption at rest, HSM key management |
| (4) Token | Spoofing | Token replay | Token expiration, single-use tokens |
| (5) Payment Processor | Repudiation | Deny transaction | Signed audit logs |
| (6) Bank Gateway | DoS | Flood requests | Rate limiting, circuit breaker |
## Trust Boundary Descriptions
| Boundary | Trust Level | Description |
|----------|-------------|-------------|
| Internet | None | Untrusted public network |
| DMZ | Low | Exposed services, filtered traffic |
| Application | Medium | Validated requests, authenticated users |
| Backend | High | Internal services, encrypted data |
| External | Medium | Third-party services, contractual trust |
The Core Question You’re Answering
“Where are the attack surfaces in this system and what threats exist at each?”
Concepts You Must Understand First
- What is a trust boundary? A line where the level of trust changes (e.g., internet to internal network).
- What is STRIDE? Threat categorization: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege.
- What is a data flow diagram (DFD)? Shows how data moves through a system with processes, data stores, and external entities.
The Interview Questions They’ll Ask
- “How do you identify trust boundaries?”
- Network segments (DMZ, internal)
- Authentication points
- Data classification changes
- Ownership/control changes
- “What’s the difference between a regular DFD and a threat model DFD?”
- Threat model DFDs explicitly show trust boundaries
- They annotate data sensitivity
- They identify where threats apply
- “How do you prioritize threats?”
- DREAD scoring (Damage, Reproducibility, Exploitability, Affected users, Discoverability)
- Risk = Likelihood x Impact
- Focus on high-value assets first
- “When should you create a threat model?”
- During design (before implementation)
- When adding new integrations
- After security incidents
- Regular reviews (quarterly)
Hints in Layers
Hint 1: Start with a context diagram, then decompose into DFDs.
Hint 2: Draw trust boundaries as dashed boxes or lines.
Hint 3: Number each data flow for easy reference.
Hint 4: Use OWASP Threat Dragon for guided threat modeling.
Books That Will Help
| Topic | Book & Chapter |
|---|---|
| Threat modeling process | “Threat Modeling: Designing for Security” by Adam Shostack |
| STRIDE methodology | “The Security Development Lifecycle” by Howard & Lipner |
| DFD notation | “Structured Analysis” by DeMarco |
Project Comparison Table
| # | Project | Difficulty | Time | Diagram Type | Primary Tool |
|---|---|---|---|---|---|
| 1 | UML Class Diagram | Beginner | 1-2 days | Static Structure | draw.io |
| 2 | Sequence Diagrams | Beginner | 1-2 days | Behavior | Mermaid |
| 3 | State Machine | Intermediate | 2-3 days | Behavior | Mermaid |
| 4 | Activity Diagram | Intermediate | 2 days | Workflow | PlantUML |
| 5 | C4 Context | Beginner | 1 day | Architecture | Structurizr |
| 6 | C4 Container | Intermediate | 2 days | Architecture | Structurizr |
| 7 | C4 Component | Intermediate | 2 days | Architecture | Structurizr |
| 8 | Deployment Diagram | Intermediate | 2 days | Infrastructure | draw.io |
| 9 | Mermaid Docs | Beginner | 1-2 days | Docs-as-Code | Mermaid |
| 10 | PlantUML Enterprise | Intermediate | 2-3 days | UML | PlantUML |
| 11 | Python Diagrams | Intermediate | 2-3 days | Infrastructure | Python |
| 12 | D2 Language | Intermediate | 2 days | Modern | D2 |
| 13 | ASCII Diagrams | Beginner | 1-2 days | Universal | Text Editor |
| 14 | ADRs | Intermediate | 2-3 days | Decision | Markdown |
| 15 | API Docs | Intermediate | 2-3 days | Developer | OpenAPI |
| 16 | System Context | Beginner | 1-2 days | Scope | Excalidraw |
| 17 | Threat Modeling | Advanced | 3-4 days | Security | Threat Dragon |
Summary
| Project | Key Learning | Recommended Path |
|---|---|---|
| 1. Class Diagram | Static structure notation | All paths |
| 2. Sequence Diagram | Interaction over time | All paths |
| 3. State Machine | Behavior modeling | Architect path |
| 4. Activity Diagram | Workflow visualization | Business analyst |
| 5. C4 Context | System boundaries | All paths |
| 6. C4 Container | Technical decomposition | Architect path |
| 7. C4 Component | Code organization | Senior developer |
| 8. Deployment | Infrastructure mapping | DevOps path |
| 9. Mermaid | Docs-as-code basics | All paths |
| 10. PlantUML | Enterprise UML | Enterprise teams |
| 11. Python Diagrams | Programmatic generation | DevOps/SRE |
| 12. D2 Language | Modern diagram syntax | Documentation lead |
| 13. ASCII | Universal compatibility | All paths |
| 14. ADRs | Decision documentation | Architect path |
| 15. API Docs | Developer experience | API teams |
| 16. System Context | Scope definition | All paths |
| 17. Threat Modeling | Security visualization | Security teams |
References
Books
- “UML Distilled” by Martin Fowler - The essential UML reference
- “Software Architecture in Practice” by Bass, Clements, Kazman - Architecture documentation
- “The Art of Visualising Software Architecture” by Simon Brown - C4 model deep dive
- “Documenting Software Architectures” by Clements et al. - Views and beyond
- “Design It!” by Michael Keeling - ADR fundamentals
- “Software Architecture: The Hard Parts” by Richards & Ford - Decision trade-offs
- “Threat Modeling: Designing for Security” by Adam Shostack - Security diagrams
Online Resources
- C4 Model: https://c4model.com
- Mermaid Documentation: https://mermaid.js.org
- PlantUML Guide: https://plantuml.com
- D2 Language: https://d2lang.com
- Structurizr: https://structurizr.com
- draw.io/diagrams.net: https://diagrams.net
- Excalidraw: https://excalidraw.com
- OWASP Threat Dragon: https://owasp.org/www-project-threat-dragon/
Tools by Category
Visual Editors:
- draw.io / diagrams.net (free, web/desktop)
- Lucidchart (paid, collaborative)
- Excalidraw (free, hand-drawn style)
- Miro/FigJam (whiteboarding)
Diagram-as-Code:
- Mermaid (embedded in markdown)
- PlantUML (Java-based, comprehensive)
- D2 (modern, clean syntax)
- Structurizr (C4 model focused)
- Python diagrams (programmatic)
Specialized:
- Threat Dragon (threat modeling)
- IcePanel (C4 collaboration)
- Archi (ArchiMate)
Complete all 17 projects to master software diagramming from informal sketches to automated documentation pipelines.