Why Every Engineer Needs a Good Architecture Diagram: Purpose, Types, and How to Create One

Purpose of Architecture Diagrams

Architecture diagrams act as a shared visual language for architects, product managers, developers and testers. They make product and technical goals explicit, reduce communication friction, and enable coordinated work across teams.

Clarify direction : visualise goals to avoid drift.

Lower communication cost : a picture conveys relationships faster than text.

Boost collaboration : all stakeholders can read the same view.

Facilitate coordination : cross‑team dependencies become obvious.

What Makes a Good Diagram

Clear structure : hierarchical viewpoint, logical flow, and a single, obvious perspective.

Visual appeal : consistent colour palette, legends and layout encourage reading.

Complete content : business, functional and module information form a closed loop.

Consistent terminology and granularity : same symbols and level of detail throughout.

Typical visual conventions include solid lines for strong coupling, hollow arrows for data flow, and solid arrows for control flow.

When to Create Diagrams

Before a complex project starts – to define system composition, boundaries and governance.

Whenever a diagram would help – even mid‑project or after completion ("the best time to plant a tree was ten years ago; the second best is now").

Diagram Classification Pyramid

Four abstraction levels form a pyramid: system‑level (overall relationships and governance), application‑level (single‑app architecture), module‑level (internal module structure), and code‑level (implementation details). The main categories are:

Business Architecture Diagram

Application Architecture Diagram

Technical Architecture Diagram

Code Architecture Diagram

Data Architecture Diagram

How to Draw Diagrams

The process starts with a clear purpose, then applies four visual design principles and three layout techniques.

Design Principles

Proximity : group related elements, separate unrelated ones.

Alignment : keep elements on common axes to create order.

Contrast : use distinct visual styles to highlight differences.

Repetition : apply consistent styles for cohesion.

Colour Usage

Primary colours (red, yellow, blue) for broad categories.

Complementary colours to emphasise key parts.

Equidistant triadic colours for harmonious palettes.

Same‑level colours for visual harmony in multi‑colour scenes.

Composition

Apply the golden‑ratio (≈0.618) to overall size and use the Fibonacci sequence (1, 1, 2, 3, 5, 8, 13…) to guide proportions. Limit the colour count to three to avoid clutter.

Step‑by‑Step Workflow

Identify all involved applications, functions, systems, modules, capabilities and platforms.

Extract business requirements from user scenarios and map them to functional modules.

Group related functions into modules, then arrange them into layers (entry, business, service, data).

Draw using standard shapes: rectangles for entities, rounded rectangles for processes, circles for connection points, ellipses for states.

Use line styles to convey meaning:

Solid line – strong coupling.

Dashed line – logical association.

Hollow‑arrow – data flow.

Solid‑arrow – control flow.

Add a legend that explains colours, line types and symbols.

Business / Product Architecture Diagram

Shows the system from a business perspective: planning, modules and processes. Typical e‑commerce principles:

Platformisation : split the system into independent platforms (transaction, logistics, payment, advertising).

Core vs. non‑core separation : keep the core order service stable; move auxiliary services (e.g., recommendation) to separate domains.

Isolation of business types : high‑availability for checkout, strong consistency for settlement, high concurrency for flash‑sale.

Main vs. auxiliary flow : prioritise resources for the main flow.

Workflow to produce a product diagram :

Map the end‑to‑end business process (closed loop) and identify participants.

Derive functional modules from the process.

Arrange modules into layers (entry, business, service, data) and draw a matrix or swim‑lane diagram.

Application Architecture Diagram

Bridges business and technology, describing logical structure, module interactions and data flow. Core guidelines:

Stability : keep the architecture simple; avoid over‑design.

Decoupling : separate stable parts from volatile ones, core from non‑core, services from data.

Abstraction : applications depend on service abstractions, not concrete implementations; databases are accessed via logical interfaces.

Loose coupling : prefer asynchronous cross‑domain calls; set time‑outs and queue sizes for synchronous calls.

Fault tolerance : service autonomy, cluster deployment, multi‑datacenter disaster recovery.

Two common views:

Application functional diagram : business modules and their functions without technical details; large systems are split into sub‑domains for readability.

Single‑application technical diagram : shows how each function is realised through layers (database → data‑access → business logic → UI). Low‑level infrastructure (servers, containers) is omitted.

Technical Architecture Diagram

Focuses on runtime components (load balancers, web servers, containers, etc.) and non‑functional attributes such as high availability, performance, scalability, security and simplicity.

Statelessness : avoid storing state locally.

Reusability : services are reusable at the business‑logic level, not at implementation detail.

Loose coupling : async cross‑domain calls; time‑outs for sync calls.

Governance : service degradation, rate limiting, feature toggles, monitoring, whitelist and contracts.

Foundation services : shared capabilities (e.g., inventory, pricing) should be autonomous and horizontally scalable.

Typical layers: access layer (LVS/Nginx), application layer (Tomcat/Node), service layer, data layer, infrastructure.

Code Architecture Diagram

Illustrates code‑level layering, e.g. Controller → Service → Mapper/DAO. UML class diagrams can show inheritance, aggregation, composition and dependency arrows. The goal is to convey how code is organised rather than business functionality.

Data Architecture Diagram

Describes data models, synchronization, backup and storage strategies. Design principles:

Unified data view – ensure timeliness, consistency, accuracy and completeness.

Consistency – decide where eventual consistency is acceptable and apply compensation mechanisms.

Separation of data and application – applications depend on logical databases only.

Heterogeneous data design – use different schemas for different business domains (e.g., buyer vs. seller data).

Read/write splitting – separate read replicas from write masters.

Sharding and partitioning for large tables.

Backup strategies – primary‑secondary replication, point‑in‑time recovery.

Recommendation: use MySQL for relational needs; introduce NoSQL or caching only when the use‑case justifies it.

Diagram Consistency and Maintenance

All diagrams should share the same visual language (shapes, line styles, colours, legends). Regularly synchronise diagrams with code changes; otherwise they lose value. Simon Brown warns, "If the diagram loses connection with the code, it cannot improve the architecture."

References

Simon Brown –

"If the diagram loses connection with the code, it cannot improve the architecture."

"Thinking in UML" – provides guidance on abstraction, hierarchy and visual notation.

《鹅厂架构师谈：如何做好架构设计？》 – discusses the pyramid view of architecture levels.