Tech Lead’s Guide: How to Create Effective System Architecture Diagrams

Definition of a Technical Architecture Diagram

A technical architecture diagram describes logical components, platforms, and their relationships. It must answer three questions:

What responsibilities does each module have? (e.g., OrderService manages the entire order lifecycle, not just creation)

How do modules depend on each other? Are connections synchronous or asynchronous?

What abstractions or design patterns are used? (DDD, layering, high‑concurrency handling)

Three‑Layer View System

First Layer – Overall Technical Architecture (Big Picture)

Shows a company‑wide macro structure. Each box represents an application or service; relationships are clear. Audience: CTOs, technical directors, product managers, new hires.

Second Layer – Domain‑Level Technical Architecture

Targets domain architects and core developers. Emphasises domain autonomy and details the technical design of a specific business domain.

Third Layer – Application‑Level Technical Architecture

For development and testing engineers. Describes the internal structure of a single service, including component breakdown, data flow, and technology stack (frameworks, libraries, middleware).

Six‑Step Drawing Method

Step 1 – Derive Technical Skeleton from Business Architecture

Map business modules directly to technical services (e.g., User Management → UserService).

Add pure‑technical modules not expressed in the business view (gateway, auth, tracing, config center).

Align granularity so that business and technical modules match 1:1 or 1:N.

Step 2 – Infer Non‑Functional Modules from Use‑Case Scenarios

High‑read concurrency (product detail page) → add Redis cache layer.

Inter‑service calls → add service discovery and load balancing.

Asynchronous processing (order‑completion points) → add message queue.

Data consistency (stock deduction & order) → add distributed transaction solution.

Flash‑sale scenarios → add rate limiter, queue, cache pre‑warming.

Financial transfers → add distributed transaction, reconciliation module, idempotent tables.

Step 3 – Extract Horizontal Layers (Cross‑Cutting Concerns)

Group common functions into DDD‑style layers (presentation, domain, application, infrastructure) and move observability (monitoring, logging, tracing) to a separate “support plane” with a light‑gray background.

Step 4 – Extract Vertical Modules (Reuse‑Downward)

Independent reusable services (auth center, messaging platform) → place at the bottom of the diagram as foundational services.

Third‑party libraries (JSON utils, ID generators) → place on the right, labeled as libs.

Result: line count reduced ~30 %, clarity improved ~50 %.

Step 5 – Add Support and Stability Modules

Observability: metrics, logging, tracing.

High‑availability: circuit breaker, rate limiter, degradation strategy, health checks.

Operations support: config center, registry, scheduler.

Security: audit, encryption, WAF.

Missing any of these indicates a production‑grade perspective is absent.

Step 6 – Produce Layered, Sharded Logical Architecture

Combine the previous steps to create a diagram that is both layered (access, application, data) and sharded by business domain (user, order, payment).

Common Pitfalls

Treating the architecture diagram as a class diagram (adding @Service, @Repository) leads to explosion.

Trying to show every call detail in one picture creates an unreadable spider‑web.

Using more than five colors without semantic meaning adds noise.

Leaving the diagram unchanged for months causes drift from the codebase.

Omitting text annotations prevents understanding of module responsibilities or protocol details.

Ignoring audience differences results in showing low‑level details to executives and high‑level view to developers.

Conclusion

The highest‑level technical architecture diagram enables the team to instantly see where changes are allowed and where they are not. A diagram is a means, not an end; its value lies in reducing communication entropy, codifying best practices, and guiding code evolution. Good diagrams evolve over time and become a shared battle map for the whole team.