Architectural Frameworks

In my experience, strictly following enterprise frameworks (like doing full TOGAF) is overkill for most modern tech companies. However, the mental models they provide are excellent for ensuring you haven't missed a blind spot.

TOGAF (The Open Group Architecture Framework)

The standard for heavy enterprise arch. The useful part is the ADM (Architecture Development Method) loop, specifically the BDAT layers:

1. Business: What are the goals? Processes?
2. Data: What are the entities? How do they move?
3. Application: What are the systems? Integrations?
4. Technology: Hardware, Cloud, Network.

---

The Zachman Framework

Think of this as a Periodic Table for enterprise assets. It's a 6x6 matrix intersecting:

• Perspectives: Planner, Owner, Designer, Builder, Subcontractor.
• Questions: What (Data), How (Function), Where (Network), Who (People), When (Time), Why (Motivation).

It enforces completeness. If you can't answer "Who" accesses the data (Security) or "Where" it lives (Infrastructure), the design is incomplete.

---

The C4 Model

Created by Simon Brown. This is my go-to for visualizing software architecture. It zooms in like Google Maps.

Why use C4? UML is too strict. Whiteboard sketches are too vague. C4 provides just enough structure to communicate design without getting bogged down in syntax.

---

C4 Model: E-Commerce Platform Example

Level 1: Context Diagram

Shows the big picture - your system and how it interacts with users and external systems.

Key Questions Answered:

• Who uses the system? (Customers, Admins, Support)
• What does it do? (Online sales platform)
• What external systems does it integrate with? (Payment, Shipping, etc.)
• How do users interact with it? (Web interface, admin panel)

Level 2: Container Diagram

Breaks down the system into containers (applications, databases, services).

Container Details:

• Web Application: Single-page React application
• API Gateway: Routes requests and handles authentication
• User Service: Manages user accounts and authentication
• Order Service: Handles order processing and workflow
• Product Service: Product catalog and inventory management
• Payment Service: Payment processing and refunds

Level 3: Component Diagram

Zooms into a single container to show its internal components.

Component Responsibilities:

• OrderController: HTTP request handling
• ValidationController: Input validation and sanitization
• OrderManager: Core business logic and orchestration
• PaymentProcessor: Payment workflow management
• InventoryManager: Stock level management
• OrderRepository: Database operations
• PaymentAdapter: External payment gateway integration

Level 4: Code (Optional)

Shows class-level details. Usually skipped unless critical for understanding.

When to Use Level 4:

• Complex algorithms need visualization
• Onboarding new team members
• Critical business logic documentation
• Refactoring discussions

Example Focus:

• Class relationships and dependencies
• Key method signatures
• Design pattern implementations

---

Practical C4 Guidelines

Best Practices

Start with Context:

• Always begin with Level 1 (Context)
• Get stakeholder agreement on scope
• Identify all users and integrations

Zoom Incrementally:

• Only go deeper when necessary
• Create Level 2 for developers/DevOps
• Create Level 3 for team-specific discussions
• Skip Level 4 unless critical

Consistency Matters:

• Use standard notation and colors
• Include legends and descriptions
• Keep diagrams focused and uncluttered
• Version control your diagrams

Common Pitfalls

Too Much Detail:

• Don't show every component at Level 2
• Avoid including all classes at Level 4
• Skip implementation details

Inconsistent Abstraction:

• Don't mix levels in same diagram
• Maintain clear separation of concerns
• Keep audience in mind

Outdated Documentation:

• Update diagrams when architecture changes
• Treat diagrams as living documents
• Link diagrams to implementation decisions