Session 03 - Presenting Architecture | Knowledge Base

C4 Model Overview

C4 Model (Simon Brown) cung cấp 4 levels of abstraction để communicate architecture. Mỗi level phục vụ audience khác nhau.

4 Levels

Level	Name	Audience	Shows	Analogy
Level 1	System Context	Everyone	Hệ thống trong bối cảnh users và external systems	Google Maps zoom out max
Level 2	Container	Technical + Management	Applications, databases, message queues	Zoom vào thành phố
Level 3	Component	Developers	Components bên trong 1 container	Zoom vào quận/huyện
Level 4	Code	Developers (optional)	Classes, interfaces	Zoom vào đường phố

Khi nào dùng level nào

Present cho CTO/VP           → Level 1 (Context)
Present cho Engineering team  → Level 1 + 2 (Context + Container)
Design review với dev team    → Level 2 + 3 (Container + Component)
Onboarding new developer      → Level 2 + 3
Code-level discussion         → Level 4 (hiếm khi cần formal diagram)

C4 Diagrams với Mermaid

Level 1 - System Context Diagram

Level 2 - Container Diagram

Mermaid Tips

Tip	Mô tả
Subgraph	Group related elements cho clarity
Direction	`TB` (top-bottom) cho hierarchy, `LR` (left-right) cho flow
Labels	Luôn có `Name<br/>Technology` trong mỗi box
Keep simple	Max 15-20 elements per diagram, split nếu nhiều hơn
Color coding	Dùng `style` hoặc `classDef` để phân biệt types
Version control	Mermaid as code → commit cùng source code

Architecture Presentation Structure

Recommended Flow (30-45 phút)

[5 phút]  Context & Problem
           → Tại sao cần architecture này?
           → Business driver là gì?

[5 phút]  Current State
           → Hệ thống hiện tại (Level 1 diagram)
           → Pain points cụ thể (với data)

[10 phút] Proposed Solution
           → Level 2 diagram (containers)
           → Key design decisions
           → Data flow cho main use cases

[10 phút] Trade-offs & Alternatives
           → Tại sao chọn approach này?
           → Đã consider gì khác?
           → What we're giving up

[5 phút]  Implementation Plan
           → Phases, timeline, milestones
           → Migration strategy

[5 phút]  Q&A
           → Prepared answers cho anticipated questions

Slide Template

Slide	Content	Diagram Type
1. Title	Architecture Proposal: [Name]	None
2. Problem	Business context, pain points, data	None / current state
3. Context	System in ecosystem	C4 Level 1
4. Containers	Technical components	C4 Level 2
5. Key Flow	Main use case walkthrough	Sequence diagram
6. Trade-offs	Comparison table	Table
7. Plan	Timeline, phases	Gantt / roadmap
8. Ask	Decision/resource needed	None

Presenting to Different Audiences

Technical Audience (Developers, Architects)

Do	Don't
Show trade-offs và reasoning	Just show final design
Discuss failure scenarios	Only happy path
Include performance numbers	Vague "it's fast"
Welcome challenges	Get defensive
Show code samples cho complex parts	Only high-level

Non-Technical Audience (PM, Business, Executives)

Do	Don't
Lead với business impact	Lead với technology
Use analogies	Use jargon
Show before/after metrics	Show architecture details
Focus on timeline và cost	Focus on how it works
1 simple diagram max	Multiple complex diagrams

Analogy Examples

Technical Concept	Business Analogy
Microservices	"Thay vì 1 nhà máy làm mọi thứ, chia thành nhiều xưởng chuyên biệt"
Load balancer	"Giống nhân viên hướng dẫn ở quầy, chia khách đều cho các cashier"
Database replication	"Bản sao dự phòng - nếu kho chính gặp sự cố, kho phụ tiếp tục hoạt động"
Message queue	"Hòm thư giữa các phòng ban - gửi yêu cầu vào, bên kia xử lý khi sẵn sàng"
Circuit breaker	"Cầu dao điện - ngắt tự động khi quá tải để bảo vệ hệ thống"
Caching	"Giống sticky note trên bàn - ghi lại thông tin hay dùng thay vì mở tủ hồ sơ mỗi lần"

Architecture Review Meeting Facilitation

Meeting Structure

Pre-meeting:
  - Share design doc ít nhất 2 ngày trước
  - Yêu cầu reviewers đọc trước và ghi comments
  - Define scope: review gì (security? scalability? cost?)

During meeting (60 phút):
  [0-10]  Author presents overview (KHÔNG đọc doc)
  [10-40] Structured discussion theo categories
  [40-50] Open Q&A
  [50-60] Decisions và action items

Post-meeting:
  - Update design doc với decisions
  - Send summary email với action items
  - Schedule follow-up nếu cần

Review Categories Checklist

Category	Key Questions
Functional	Có meet requirements không? Missing use cases?
Scalability	Handle 10x traffic thế nào? Bottlenecks ở đâu?
Reliability	Single points of failure? Recovery time?
Security	Authentication, authorization, data protection?
Operability	Monitoring, alerting, debugging, deployment?
Cost	Infrastructure cost reasonable? Hidden costs?
Complexity	Có quá complex không? Team maintain được không?
Migration	Migration path từ current state? Rollback plan?

Decision Framework

After discussion, categorize:

APPROVED:     Ready to proceed
APPROVED WITH CONDITIONS: Proceed nhưng cần address [specific items]
NEEDS REVISION: Major concerns, revise và review lại
REJECTED:     Fundamental issues, consider alternative approach

Visual Storytelling

Principles

Principle	Application
Progressive disclosure	Bắt đầu simple (Level 1), drill down dần
Highlight what matters	Dùng color/bold cho phần đang discuss
Before → After	Show current state vs proposed state
Animation/Build	Reveal diagram từng phần (trong slides)
Consistent notation	Cùng shape = cùng type (rectangle = service, cylinder = DB)

Color Convention

Element	Color	Meaning
New/Changed	Green / Blue	Phần thay đổi
Existing	Gray	Giữ nguyên
Deprecated	Red / Strikethrough	Sẽ bỏ
External	Orange	Third-party
Focus area	Bold border	Đang discuss

Diagram Dos and Don'ts

DO:
  ✓ Mỗi diagram có title và legend
  ✓ Label mọi arrows (data flow, protocol)
  ✓ Include technology trong box labels
  ✓ Max 15 elements per diagram
  ✓ Consistent layout direction

DON'T:
  ✗ Diagram quá phức tạp, nhiều crossing lines
  ✗ Missing labels trên connections
  ✗ Mix abstraction levels trong 1 diagram
  ✗ Diagram không có context (title, scope)
  ✗ Quá đẹp mà không informative