The Art of Arrow Direction in Architecture Diagrams: Accurately Conveying System Design

by

🌏 閱讀中文版本

Why Arrow Direction in Architecture Diagrams Matters

In software engineering and system design, architecture diagrams are core tools for team communication and technical decision-making. A clear architecture diagram can:

  • Reduce misunderstandings: Accurate arrow direction prevents team confusion about data flow and service dependencies
  • Accelerate decisions: Clear visual representation helps technical decision-makers quickly identify system bottlenecks
  • Lower costs: Incorrect architecture understanding can lead to significant development rework; proper arrow direction prevents these losses
  • Promote collaboration: Unified arrow conventions make cross-team communication smoother

According to software engineering research, 60% of system architecture misunderstandings stem from unclear visual representation. Arrow direction, as a core element of architecture diagrams, cannot be overlooked.

Basic Principles of Arrow Direction

1. Data Flow Principle

Arrows should point in the direction of data flow, not merely indicate “relationships.”

Scenario Correct Representation Incorrect Representation
API Call Client → Server Client ↔ Server
Database Query Application → Database Database → Application
Message Queue Producer → Queue → Consumer Producer ↔ Queue ↔ Consumer
Event Publishing Publisher → Event Bus → Subscriber Event Bus ↔ All Services

2. Temporal Principle

In sequence diagrams or flowcharts, arrows should reflect the order of events:

  • Top to bottom: Represents time progression
  • Left to right: Represents logical sequence
  • Numeric labeling: Use numbers when the flow is complex (1→2→3)

3. Dependency Principle

Arrow direction should express who depends on whom:

Service A → Service B  (means: A depends on B, A calls B's functionality)
Database ← Application (means: Application writes to database)

4. Correct Use of Bidirectional Arrows

Avoid overusing bidirectional arrows. They should only be used in:

  • True bidirectional communication (e.g., WebSocket, gRPC bidirectional streaming)
  • Mutually dependent services (should be avoided in architecture)
  • Data synchronization (e.g., primary-replica database replication)

Common Arrow Types and Meanings

Solid Arrow

Represents strong dependency or primary data flow:

  • Synchronous API calls
  • Database read/write operations
  • File system access
  • Required service dependencies

Dashed Arrow

Represents weak dependency or secondary data flow:

  • Asynchronous messaging
  • Event notifications
  • Cache updates
  • Optional service dependencies

Thick Arrow

Represents high traffic or critical path:

  • High-frequency API calls
  • Large data transfers
  • Performance-critical paths
  • Traffic requiring monitoring

Color Coding

Color Suggested Use Example
Black/Gray General data flow Standard API calls
Blue Read operations Database queries, cache reads
Green Write operations Database updates, file writes
Red Error handling or alerts Exception flows, monitoring alerts
Orange Security-related Authentication flows, encrypted channels

Arrow Application in Layered Architecture

Three-Tier Architecture

In classic three-tier architecture, arrow direction should clearly express layer dependencies:

Presentation Layer
    ↓ (User Request)
Business Logic Layer
    ↓ (Data Access)
Data Layer
    ↑ (Data Response)

Key Principles:

  • Upper layers can call lower layers (downward arrows)
  • Lower layers should not directly depend on upper layers (avoid upward arrows)
  • Response data can use different colors or dashed lines

Microservices Architecture

Arrow usage in microservices architecture is more complex, requiring consideration of:

  • Synchronous calls: Solid arrows, annotated with REST, gRPC, etc.
  • Asynchronous messages: Dashed arrows, annotated with message queues (Kafka, RabbitMQ)
  • Event-driven: Diverging arrows from event publishers to multiple subscribers
  • Data replication: Bidirectional dashed arrows, annotated with sync mechanism

Event-Driven Architecture

Arrow representation in event-driven architecture requires special attention:

Order Service --[OrderCreated Event]→ Event Bus
                                      ↓
                        +--------------+---------------+
                        ↓              ↓               ↓
                  Inventory       Notification      Analytics
                  Service          Service          Service

Best Practices:

  • Annotate arrows with event names
  • Use dashed lines to indicate asynchronous nature
  • Clearly mark event bus or message queue

Arrow Strategies in Complex Systems

1. Layered Views

When systems are too complex, split architecture diagrams into multiple layers:

  • High-level view: Show only major services and critical data flows
  • Mid-level view: Expand specific domain service interactions
  • Low-level view: Detailed display of single service internal architecture

2. Grouping

Use boundary boxes to group related services:

┌─── Payment Domain ──────────┐
│  Payment Service → Gateway  │ → External Bank
│      ↓                      │
│  Transaction Log Service    │
└─────────────────────────────┘

3. Reference Number System

When arrows are too numerous, use a numbering system:

  • Mark arrow numbers on the diagram (①, ②, ③)
  • Provide detailed explanations in legend or documentation
  • Include protocol, data format, expected traffic, etc.

4. Abstraction Level Control

Avoid mixing different abstraction levels of arrows in the same diagram:

Abstraction Level Appropriate to Show Not Appropriate
System Level Service interactions Class method calls
Service Level Module dependencies Database table relationships
Module Level Class associations Network packet flow

Drawing Tools and Techniques

Draw.io (diagrams.net)

Advantages:

  • Free and open-source
  • Rich library of prebuilt icons (AWS, Azure, GCP)
  • Supports multiple arrow styles and colors
  • Integrates with VS Code, Confluence

Arrow Best Practices:

  • Use “Style” panel to adjust line thickness (1-3pt)
  • Set arrow end styles (Classic, Block, Diamond)
  • Use “Waypoints” to adjust arrow paths, avoid crossings

PlantUML

Advantages:

  • Text-based definition, easy version control
  • Automatic layout, reduces manual adjustment
  • Supports UML, sequence diagrams, component diagrams

Arrow Syntax Examples:

@startuml
!define RECTANGLE rectangle

RECTANGLE "Web App" as webapp
RECTANGLE "API Gateway" as api
RECTANGLE "Auth Service" as auth
RECTANGLE "Database" as db

webapp -> api : HTTP Request (1)
api -> auth : Validate Token (2)
auth -> db : Query User (3)
db --> auth : User Data (4)
auth --> api : Token Valid (5)
api --> webapp : JSON Response (6)
@enduml

Arrow Types:

  • ->: Solid arrow (synchronous call)
  • -->: Dashed arrow (response or asynchronous)
  • -[#red]->: Red arrow (error flow)
  • -[#0000FF,thickness=3]->: Thick blue arrow (high traffic)

Mermaid

Advantages:

  • Can be embedded directly in Markdown (GitHub, GitLab native support)
  • Concise syntax, low learning curve
  • Suitable for quickly drawing simple architecture diagrams

Flowchart Example:

graph LR
    A[User] -->|HTTPS| B[CDN]
    B -->|Cache Miss| C[Load Balancer]
    C -->|Round Robin| D[App Server 1]
    C -->|Round Robin| E[App Server 2]
    D -->|Read| F[(Primary DB)]
    E -->|Read| G[(Replica DB)]
    F -.->|Replication| G

C4 Model (Context, Containers, Components, Code)

C4 Model is a structured architecture visualization method that clearly defines arrow usage at different levels:

  • Level 1 (Context): System interaction with external entities
  • Level 2 (Containers): Arrows between applications, databases, microservices
  • Level 3 (Components): Dependency arrows between modules, classes
  • Level 4 (Code): UML class diagram level arrows

Real-World Case Studies

Case 1: E-commerce Platform Architecture

Incorrect Example (common issues):

User Interface ↔ API Gateway ↔ Order Service ↔ Database
                ↕
           Payment Service

Problems:

  • All bidirectional arrows, cannot see data flow direction
  • Payment service position is unclear
  • Missing load balancers, caches, and other key components

Correct Example:

User → [CDN] → Load Balancer → API Gateway
                                    ↓
                    +---------------+----------------+
                    ↓                                ↓
              Order Service                    Payment Service
                ↓                                   ↓
           [Redis Cache]                      [Payment Gateway]
                ↓                                   ↑
              Database ←------ Async Notify ------┘

Legend:
→  Synchronous HTTP/REST call
--→ Asynchronous message/event
[ ] Third-party service or infrastructure

Case 2: Microservices Event-Driven Architecture

Requirement: Show event propagation after order creation

Correct Representation:

Order Service --[OrderCreated]--> Kafka Topic: orders
                                    │
                    +---------------+----------------+
                    ↓               ↓                ↓
              Inventory        Notification       Analytics
              Service           Service            Service
                ↓                ↓                  ↓
           Update Stock      Send Email        Update Dashboard
                ↓
              Database
                ↓
    --[InventoryUpdated]--> Kafka Topic: inventory

Arrow Legend:
--[EventName]--> Publish event to Kafka
↓ Synchronous processing flow

Case 3: Hybrid Cloud Architecture

Scenario: On-premises data center integrated with AWS cloud

Key Points:

  • Use different colors to distinguish on-prem vs. cloud
  • Mark network boundaries (VPN, Direct Connect)
  • Clearly indicate data flow direction and security controls
┌─── On-Premises Data Center (Gray) ───┐
│                                       │
│  App Server → Internal API            │
│       ↓                               │
│   Primary Database                    │
│       ↓                               │
└───────┼───────────────────────────────┘
        ↓ (VPN or Direct Connect)
┌───────┼─── AWS VPC (Blue) ────────────┐
│       ↓                               │
│  Replica Database (RDS)               │
│       ↑                               │
│   [Data Sync]                         │
│       ↓                               │
│  S3 (Backup Storage)                  │
└───────────────────────────────────────┘

Arrow Legend:
→  Application call
↓  Data replication
[X] Secure channel (encrypted)

Frequently Asked Questions

Q1: When should bidirectional arrows be used?

A: Bidirectional arrows should be used cautiously, limited to:

  • ✅ True bidirectional communication: WebSocket, gRPC bidirectional streaming
  • ✅ Primary-replica data sync: Database replication, file sync
  • ✅ Mutually dependent services: But this is usually an architecture anti-pattern and should be avoided
  • ❌ Avoid using for: General request-response patterns (use unidirectional arrows with different colors or dashed lines for responses)

Q2: How to handle crossing arrows in architecture diagrams?

A: Arrow crossings reduce readability. Solutions:

  1. Rearrange component positions: Place closely related services near each other
  2. Use waypoints: Adjust arrow paths in tools like draw.io
  3. Layered views: Split complex architecture into multiple diagrams
  4. Use “bridge” symbols: When arrows must cross, use semicircle symbols to indicate crossover
  5. 3D layers: Use shadows or Z-axis depth to distinguish different arrow levels

Q3: Should architecture diagrams include error handling flow arrows?

A: Depends on the diagram’s purpose and complexity:

  • High-level architecture diagrams: Usually not included, to avoid excessive complexity
  • Detailed flow diagrams: Should be included, using red or dashed arrows for exception paths
  • Best practice: Use annotations in main architecture diagrams (e.g., “*includes error retry mechanism”), then provide separate error handling flow diagrams

Q4: How to represent load balancing in architecture diagrams?

A: Several common representation methods:

  1. Fan-out distribution: 
    Load Balancer
    ├──→ Server 1
    ├──→ Server 2
    └──→ Server 3
  2. Group representation: 
    Load Balancer → [Server Pool (3x)]
  3. Annotate distribution strategy: 
    Load Balancer --[Round Robin]--> Server Pool

Q5: Should data formats be annotated on arrows?

A: Depends on diagram purpose:

  • System overview diagrams: Usually not needed, only annotate protocols (HTTP, gRPC, AMQP)
  • Integration diagrams: Should be annotated, especially for cross-system integration (JSON, XML, Protobuf)
  • API documentation diagrams: Must be annotated, including request and response formats

Example:

Client --[POST /api/orders, JSON]--> API Gateway
API Gateway --[Protobuf via gRPC]--> Order Service

Q6: How to represent conditional data flows?

A: Use diamond decision symbols and annotate conditions:

User Request → Auth Service → {Logged in?}
                            ├─ Yes → Main Service
                            └─ No → Login Page

Or use color coding:

User → Cache --[Green: Cache Hit]--> Return Data
          ↓
       [Red: Cache Miss] → Database

Q7: How to represent “read” and “write” operations?

A: Several methods:

  1. Color distinction: Blue (read), green (write)
  2. Arrow annotation: 
    Application --[Read]--> Database
Application --[Write]--> Database
  3. Separate architecture diagrams: Read-write separation architecture can use different diagrams: 
    Read Path: App → Read Replica
Write Path: App → Primary → Replica Replication

Best Practice Checklist

Planning Phase

  • ✅ Determine the target audience (executives, dev team, ops team)
  • ✅ Choose appropriate abstraction level (system, service, component, code)
  • ✅ Decide if multiple views are needed (high-level, detailed, domain-specific)
  • ✅ Create a legend defining arrow types and color meanings

Drawing Phase

  • ✅ Use consistent arrow styles (solid/dashed, thickness, color)
  • ✅ Annotate data flow direction, avoid ambiguous bidirectional arrows
  • ✅ Annotate arrows with protocols or technologies (REST, gRPC, Kafka)
  • ✅ Use color or line styles to distinguish different interaction types
  • ✅ Avoid arrow crossings, adjust component positions when necessary
  • ✅ Use numbering system for complex flows (1→2→3)
  • ✅ Maintain consistent direction (prefer left-to-right, top-to-bottom)

Complexity Management

  • ✅ Keep component count per diagram under 10-15
  • ✅ Keep arrow count under 20 (consider layering if exceeded)
  • ✅ Use groups to encapsulate related services
  • ✅ Provide zoom-in view links to expand complex areas
  • ✅ Consider using reference numbers with detailed documentation

Documentation Phase

  • ✅ Add legend to diagrams
  • ✅ Provide version number and date to track architecture evolution
  • ✅ Add annotations to critical arrows (traffic size, SLA requirements)
  • ✅ List assumptions and constraints (e.g., “assumes 99.9% availability”)
  • ✅ Include contact information or responsible team

Maintenance Phase

  • ✅ Put architecture diagrams in version control (Git)
  • ✅ Regularly review and update (at least quarterly)
  • ✅ Update synchronously during major architecture changes
  • ✅ Collect team feedback to improve readability
  • ✅ Create evolution history, preserve old versions for reference

Review Checklist

Before publishing architecture diagrams, ask yourself:

  1. Can someone unfamiliar with the system understand main data flows in 5 minutes?
  2. Are arrow directions clear and consistent, without ambiguity?
  3. Are there too many crossings affecting readability?
  4. Is the legend complete, covering all symbols used?
  5. Is the abstraction level consistent, without mixing high and low details?
  6. Are key technical details annotated (protocols, data formats, traffic)?
  7. Does the diagram have a version number and update date?

Summary

Arrow direction in architecture diagrams is not just a visual element, but a critical tool for accurately conveying system design intent. By following data flow principles, temporal principles, and dependency principles, and skillfully using different arrow types and color coding, we can create clear and understandable architecture diagrams.

In complex systems, using layered views, grouping, reference numbers, and other strategies can effectively manage complexity. Choosing appropriate tools (draw.io, PlantUML, Mermaid) and following structured methods like the C4 Model can enhance the professionalism and consistency of architecture diagrams.

Remember: A good architecture diagram should be like a map, allowing readers to quickly find the information they need and accurately understand how the system works. Arrow direction is the compass of this map—use it wisely.

Related Articles

Related posts:

  1. 架構圖箭頭方向的藝術：準確傳達系統設計
  2. 實踐篇：在雲服務平台中應用架構圖箭頭方向
  3. AWS 到 GCP 架構轉換完整指南：服務對應、遷移策略與實踐
  4. “深入解析 Git 隱藏檔案：.gitkeep、.gitignore、.gitattributes 的真正用途與最佳實踐”

Leave a Comment