Chapter 23 Flashcards — Diagramming Architecture
flashcards fsa diagramming architecture-documentation
C4 Model
Q1: What does C4 stand for, and who created it?
A1: C4 stands for Context, Containers, Components, Code — four levels of zoom for documenting a software system. Created by Simon Brown.
Q2: What does a C4 Level 1 (Context) diagram show, and who is the primary audience?
A2: The system in its business environment — what the system does, who uses it (human actors), and which external systems it integrates with. No technology details. Primary audience: business stakeholders and executives.
Q3: What does a C4 Level 2 (Container) diagram show?
A3: The deployable/runnable units within the system — web apps, APIs, databases, message queues, mobile apps. Shows technology choices (e.g., “Spring Boot API”, “PostgreSQL database”) and communication protocols between containers. Audience: architects, senior developers, DevOps.
Q4: What does a C4 Level 3 (Component) diagram show?
A4: The major components inside a single container — modules, controllers, services, repositories, and their interactions. One Level 3 diagram zooms into one container from the Level 2 diagram. Audience: developers.
Q5: What does a C4 Level 4 (Code) diagram show, and when is it typically skipped?
A5: Class/entity level detail — UML class diagrams, ER diagrams. This level is typically skipped or auto-generated from code because it becomes stale quickly and adds limited architectural value beyond what an IDE can show.
Q6: What is the key structural rule that connects C4 levels to each other?
A6: Each level zooms into one element from the level above. A Container diagram zooms into one box from the Context diagram; a Component diagram zooms into one container from the Container diagram.
UML vs C4 vs ArchiMate
Q7: When should you choose UML over C4?
A7: Use UML when you need precise, formal notation for detailed technical design — sequence diagrams for interface contracts, class diagrams for type hierarchies, state machine diagrams for object lifecycles. UML is best for developer-to-developer communication at the implementation level.
Q8: When should you choose ArchiMate, and what three layers does it model?
A8: Use ArchiMate for enterprise architecture programs aligned with TOGAF. It models three layers: Business layer (processes, actors, services), Application layer (application components and services), and Technology layer (servers, networks, infrastructure).
Q9: What is the primary advantage of C4 over UML for stakeholder communication?
A9: C4 has a much lower learning curve (4 levels, simple rectangle shapes) and targets different diagrams to different audiences, making it accessible to non-technical stakeholders at Level 1 and precise for developers at Levels 3-4. UML’s 14 diagram types and formal notation create a high barrier.
Q10: Which stakeholder audience is ArchiMate designed for, and why is it inappropriate for a single product team?
A10: ArchiMate targets enterprise architects, CTOs, and EA boards. It is inappropriate for a single product team because its multi-layer meta-model is complex to learn and maintain, and it models entire enterprise IT portfolios — far more scope than a single product requires.
Code-as-Diagrams Tools
Q11: Name three code-as-diagrams tools and their key differentiator from drawing tools like draw.io.
A11: PlantUML (text DSL), Mermaid (Markdown-embedded DSL), Structurizr (C4-aware DSL). Key differentiator: diagrams are stored as text files in source control, allowing them to be versioned, diffed, and updated alongside code — reducing diagram staleness.
Q12: What is Structurizr’s key advantage over PlantUML and Mermaid for architecture documentation?
A12: Structurizr uses the Structurizr DSL which is C4-model-aware — you define a workspace model once and generate multiple C4 views (Context, Container, Component) from that single model. PlantUML and Mermaid treat each diagram independently.
Q13: What is the primary trade-off when using code-as-diagrams tools vs. drawing tools?
A13: Code-as-diagrams tools sacrifice WYSIWYG visual editing for version control and automation. Layout is controlled by the tool (not the author), so visual polish is limited — but diagrams can be auto-rendered in CI/CD pipelines and embedded in documentation sites.
Q14: What is Mermaid’s standout integration advantage?
A14: Mermaid diagrams render natively in GitHub and GitLab Markdown — you write a Mermaid code block in a README or wiki page and the platform renders it automatically, with no external tool or image export required.
Whiteboard and Drawing Tools
Q15: When are whiteboard tools (Miro, Mural, FigJam) appropriate, and when are they NOT appropriate?
A15: Appropriate for brainstorming sessions, architecture workshops, and exploratory design where real-time collaboration matters. Not appropriate as a system of record — diagrams created in whiteboard tools are not version-controlled and drift from reality without discipline.
Q16: What category does draw.io (diagrams.net) belong to, and what is its main limitation?
A16: Drawing tool (persistent, shareable diagrams). Main limitation: manual maintenance — there is no linkage to code, so diagrams must be updated by hand whenever the architecture changes. Integrates with Confluence and Google Drive for storage.
Diagram Guidelines
Q17: Why are titles and descriptions mandatory on every architecture diagram?
A17: Without a title, readers cannot determine what is being shown. Without a description, readers cannot determine why the diagram exists, what question it answers, or whether it is current. These are the minimum metadata required for a diagram to be useful.
Q18: What must every arrow (relationship line) on an architecture diagram include, and why?
A18: Every arrow must include: (1) directionality (arrowhead showing data/control flow direction) and (2) a label describing what the relationship means (e.g., “sends order events via Kafka”, “HTTP GET /api/orders”). An undirected, unlabeled line communicates no architectural information.
Q19: Why is a legend required on every diagram even when you use a consistent visual language?
A19: Readers may not have seen your previous diagrams or memorized your visual conventions. A legend in the corner of every diagram removes ambiguity about shape meaning, color meaning, and line style meaning — it makes the diagram self-contained.
Q20: What is the “match abstraction to audience” principle in C4, and give an example of violating it?
A20: Each diagram level should contain exactly the information its target audience needs. Violation example: including database technology names (a Container-level detail) on a Context diagram shown to executives — the extra detail adds noise and distracts from the business-level story.
Q21: What does it mean for a diagram to “tell a story,” and how do you test whether a diagram achieves this?
A21: A diagram tells a story when a knowledgeable reader can follow the narrative independently without a verbal tour. Test: hand the diagram to someone unfamiliar with the system and see if they can explain what it shows. If they need 10 minutes of explanation, the diagram has failed its communication purpose.
Q22: What layout principle reduces visual confusion in architecture diagrams, and how do you achieve it?
A22: Minimize crossing lines — lines that cross create visual confusion and suggest unintended relationships. Achieve it by reorganizing component layout so lines flow in consistent directions (e.g., top-to-bottom, left-to-right), using auto-layout features, and manually adjusting positions.
Antipatterns
Q23: What is the “Big Ball of Mud Diagram” antipattern?
A23: A diagram where every component is connected to every other component with unlabeled, often bidirectional arrows. It technically shows all relationships but communicates nothing useful — the reader cannot identify which relationships matter or what they mean.
Q24: Why are stale diagrams considered more dangerous than having no diagrams at all?
A24: A missing diagram tells readers “I don’t know” — they know to investigate. A stale diagram misleads readers into false confidence: they believe they understand a system based on outdated information and make architectural, integration, or debugging decisions based on that false understanding.
Q25: What is the “wrong level of abstraction” antipattern in C4 diagrams?
A25: Mixing elements from different C4 levels in a single view — for example, showing both deployable containers (Level 2) and internal components (Level 3) in the same diagram. Readers cannot tell which level they are reading, making it impossible to reason about what details are present or missing.
Total Cards: 25
Estimated Review Time: 25-30 minutes
Priority: MEDIUM
Last Updated: 2026-05-29