Introduction

A high-level diagram provides a simplified visual representation of a system's architecture. It shows the major components, their responsibilities and the important connections between them without including source-code, class or function-level implementation details.

A useful high-level diagram helps a reader answer:

• Who or what interacts with the system?
• Where does external traffic enter?
• Which components implement the main capabilities?
• Where is data stored?
• Which interactions are synchronous?
• Which work is performed asynchronously?
• Which systems or providers are external dependencies?
• Where are important trust and ownership boundaries?
• Which path handles each major request?

In your System Design curriculum, high-level diagrams appear as Topic 1.5 under System Design Process and Estimation. The topic follows requirements discovery, functional and non-functional requirements, constraints and request flow. This order ensures that diagrams represent discovered needs instead of an arbitrary collection of technologies.

Prerequisites

What Is a High-Level Diagram?

A high-level diagram presents the macro-level structure of a system. It focuses on major subsystems, services, storage components, interfaces and external dependencies.

High-level design is commonly described as an overview of a system's major components and their interactions, without going into internal coding and implementation details.

High-Level vs Low-Level Design

Purpose of a High-Level Diagram

A high-level diagram supports several activities:

• Communicating the proposed architecture
• Confirming the system boundary
• Connecting requirements to components
• Tracing important request flows
• Identifying external dependencies
• Reviewing trust and data boundaries
• Finding missing responsibilities
• Discussing bottlenecks and failure points
• Comparing architecture alternatives
• Guiding later detailed design

The diagram is a communication and reasoning tool. It does not replace requirements, request-flow descriptions, API contracts, data models or operational documentation.

Core Elements of a High-Level Diagram

Basic Diagram Notation

A diagram does not need complicated notation, but it must remain consistent. Include a legend when symbols or line styles have special meanings.

[Rectangle]        Application or service
[(Cylinder)]       Database or durable store
[[Rounded box]]    Queue or event stream
[Person/Client]    Human or client application
[Dashed boundary]  Ownership, trust or deployment boundary

Solid arrow        Synchronous request or direct call
Dashed arrow       Asynchronous message or event
Double arrow       Request and response when explicitly needed

Show the System Boundary

The system boundary separates components owned by the proposed system from users, external services and existing platforms.

External Actors and Systems

[Web Client]                              [Identity Provider]
      |                                           |
      |                                           |
      v                                           v
+----------------------------------------------------------+
|               URL Shortener Platform                     |
|                                                          |
|  [API Gateway] -> [Link Service] -> [(Link Database)]    |
|                                                          |
+----------------------------------------------------------+

A clear boundary helps readers distinguish internal architecture from external dependencies.

Identify Major Components

Components should be derived from important responsibilities, not from fashionable technology categories.

Responsibility-first Method

1. Review the functional requirements.
2. Review the important request flows.
3. Identify major responsibilities.
4. Group related responsibilities.
5. Separate responsibilities that have different scale, security or availability needs.
6. Define data ownership.
7. Add only the components required to support the selected design.

API Gateway
Microservice A
Microservice B
Kafka
Redis
NoSQL
Kubernetes

Link Service
- Creates and manages short-link mappings

Redirect Service
- Resolves active short codes

Analytics Consumer
- Processes redirect events

Safety Service
- Evaluates destination and abuse rules

Link Store
- Owns authoritative mappings

Technology choices can be added after the responsibilities and design pressures are understood.

Label Important Connections

An unlabeled arrow can mean an HTTP call, database operation, event, replication stream or administrative dependency. Label connections that influence design understanding.

[Client]
    |
    | HTTPS: create link
    v
[Link API]
    |
    | synchronous command
    v
[Link Service]
    |
    | transactional write
    v
[(Link Database)]

[Redirect Service]
    |
    | asynchronous RedirectRecorded event
    v
[[Event Stream]]

Useful connection labels include:

• Protocol or communication style
• Request, command or event name
• Read or write direction
• Synchronous or asynchronous behaviour
• Authentication or trust requirement
• Important data category

Synchronous and Asynchronous Connections

Show Data Stores Clearly

A high-level diagram should identify major data stores and their purpose. Avoid placing a generic database icon without explaining which data it owns.

[Service] -> [(Database)]

[Link Service]
      |
      | Create or update authoritative mapping
      v
[(Link Mapping Store)]

[Analytics Consumer]
      |
      | Append processed redirect event
      v
[(Analytics Store)]

For each major store, clarify:

• Which component owns the data
• What type of data is stored
• Whether the store is authoritative or derived
• Which components may read or write it
• Whether data is cached, indexed or replicated
• Which retention or residency constraints apply

Represent Caches Carefully

A cache is not merely a performance box. The diagram and supporting notes should explain how cached data relates to authoritative data.

                    +--------------------+
                    |   Redirect Cache   |
                    +--------------------+
                       ^              |
                       | hit          | miss
                       |              v
[Redirect Service] ------------> [(Link Store)]
        |
        | redirect response
        v
     [Visitor]

Document:

• The key and value being cached
• The authoritative source
• Cache population strategy
• Expiration or invalidation strategy
• Acceptable staleness
• Behaviour when the cache is unavailable

Represent Queues and Event Streams

Use queues or streams in the diagram only when asynchronous work, buffering, decoupling or event distribution is required.

[Redirect Service]
        |
        | RedirectRecorded event
        v
[[Redirect Event Stream]]
        |
        +------------------+
        |                  |
        v                  v
[Analytics Worker]   [Abuse Worker]
        |                  |
        v                  v
[(Analytics Store)]  [(Safety Signals)]

Supporting notes should define:

• Producer
• Message or event meaning
• Consumers
• Ordering needs
• Duplicate-handling policy
• Retry policy
• Failure or dead-letter handling
• Retention and replay rules

Show Trust Boundaries

Trust boundaries identify locations where data or requests move between environments with different security assumptions.

Untrusted Network
------------------------------------------------------------

[Public Client]
      |
      | HTTPS
      v

Public Edge Boundary
============================================================

[Edge Protection] -> [API Gateway]

Protected Service Boundary
============================================================

[Link Service] -> [(Link Store)]

Important trust-boundary questions include:

• Where is external input first received?
• Where is identity validated?
• Where is authorization enforced?
• Where is transport encryption terminated?
• Which components can access sensitive data?
• Which calls cross network or organizational boundaries?
• Where are quotas and abuse controls enforced?

Logical vs Deployment Diagram

Keep logical responsibilities separate from deployment details unless the diagram has an explicit deployment purpose.

Logical Diagram

[Client]
   |
   v
[Link Service]
   |
   +----> [(Link Store)]
   |
   +----> [[Event Stream]]

This diagram explains responsibilities and interactions.

Deployment Diagram

Region A
+--------------------------------------------------+
|                                                  |
|  Public Subnet                                   |
|  [Load Balancer]                                 |
|          |                                       |
|  Private Service Network                         |
|  [Service Instance 1] [Service Instance 2]       |
|          |                |                      |
|          +-------+--------+                      |
|                  |                               |
|          [(Managed Data Store)]                  |
|                                                  |
+--------------------------------------------------+

This diagram explains placement, network boundaries and runtime topology. Avoid combining every logical and physical detail into one unreadable view.

Recommended Diagram Views

Context Diagram

The context diagram is often the first architectural view. It shows the complete system as one unit and identifies external actors and systems.

                         [Identity Provider]
                                  |
                                  |
[Link Creator] ---> +---------------------------+ <--- [Administrator]
                    |                           |
[Visitor] --------> |   URL Shortener System    |
                    |                           |
                    +---------------------------+
                                  |
                                  v
                         [Safety Provider]

The context view should not display internal databases, caches or service instances. Its primary purpose is to communicate scope and external relationships.

Component Diagram

A component diagram opens the system boundary and shows major internal responsibilities.

+----------------------------------------------------------------+
|                   URL Shortener Platform                       |
|                                                                |
|  [API Gateway]                                                 |
|       |                                                        |
|       +--------> [Link Service] -------> [(Link Store)]         |
|       |                 |                                      |
|       |                 +-------> [Safety Service]              |
|       |                                                        |
|       +--------> [Redirect Service] ---> [Redirect Cache]       |
|                            |                    |               |
|                            +--------------------+               |
|                            |                                    |
|                            +------> [(Link Store)]               |
|                            |                                    |
|                            +------> [[Redirect Events]]          |
|                                            |                   |
|                                            v                   |
|                                  [Analytics Consumer]           |
|                                            |                   |
|                                            v                   |
|                                  [(Analytics Store)]            |
|                                                                |
+----------------------------------------------------------------+

Sequence Diagram

A sequence diagram shows the order of interactions for one important request flow.

Redirect Sequence

Visitor       Edge       Redirect Service       Cache       Link Store
   |            |                |                 |              |
   | GET /abc   |                |                 |              |
   |----------->|                |                 |              |
   |            | Forward        |                 |              |
   |            |--------------->|                 |              |
   |            |                | Lookup abc      |              |
   |            |                |---------------->|              |
   |            |                | Cache miss      |              |
   |            |                |<----------------|              |
   |            |                | Read mapping                   |
   |            |                |------------------------------->|
   |            |                | Mapping                        |
   |            |                |<-------------------------------|
   |            |                | Populate cache  |              |
   |            |                |---------------->|              |
   |            | Redirect       |                 |              |
   |            |<---------------|                 |              |
   | 302        |                |                 |              |
   |<-----------|                |                 |              |

Separate sequence diagrams should normally be created for the create-link flow, redirect flow, deactivation flow and important failure flows.

Complete URL Shortener High-Level Diagram

                                  +-------------------+
                                  | Identity Provider |
                                  +---------+---------+
                                            |
                                            | Token validation
                                            |
+---------------+                  +---------v---------+
| Web / Mobile  |---- HTTPS ------>|  Edge / Gateway   |
|    Client     |                  +----+----------+---+
+---------------+                       |          |
                                        |          |
                               Create / Manage     | Redirect
                                        |          |
                               +--------v--+   +---v--------------+
                               |   Link    |   |     Redirect     |
                               |  Service  |   |      Service     |
                               +----+------+   +----+---------+---+
                                    |               |         |
                    Validate URL    |               |         | Cache lookup
                                    |               |         v
                               +----v------+        |   +-------------+
                               |  Safety   |        |   | Redirect    |
                               |  Service  |        |   | Cache       |
                               +-----------+        |   +------+------+ 
                                                    |          |
                                    Store mapping   |          | Miss
                                          |         |          |
                                          v         v          v
                                    +-----------------------------+
                                    |       Link Mapping Store    |
                                    +-----------------------------+

                               Redirect Service
                                      |
                                      | RedirectRecorded event
                                      v
                               +---------------+
                               | Event Stream  |
                               +-------+-------+
                                       |
                                       v
                               +---------------+
                               | Analytics     |
                               | Consumer      |
                               +-------+-------+
                                       |
                                       v
                               +---------------+
                               | Analytics     |
                               | Store         |
                               +---------------+

Diagram Explanation

1. Web and mobile clients send link-management and redirect requests through the system entry point.
2. The edge or gateway handles routing and applicable cross-cutting controls.
3. The Link Service owns link-creation and management operations.
4. The Identity Provider participates in authenticated owner workflows.
5. The Safety Service evaluates destination or abuse rules defined by the requirements.
6. The Link Mapping Store is the authoritative store for short-code mappings.
7. The Redirect Service handles the read-heavy redirect path.
8. The Redirect Cache reduces repeated access to eligible mappings.
9. Redirect events are transferred asynchronously.
10. The Analytics Consumer processes redirect events separately from the critical redirect response.

Show Important Failure Behaviour

The main diagram should remain readable, but critical failure and fallback behaviour must not be ignored. Use annotations or a separate failure view.

[Redirect Service]
        |
        | Cache lookup
        v
[Redirect Cache]
        |
        +-- Hit -----------------> Return mapping
        |
        +-- Miss ----------------> Read Link Store
        |
        +-- Cache unavailable ---> Read Link Store when policy permits

[Link Store unavailable]
        |
        +-- No safe cached value --> Controlled error
        |
        +-- Eligible cached value -> Follow approved stale-read policy

Annotate Quality Requirements

Quality requirements can be connected to the architecture using concise annotations rather than overcrowding the diagram.

[Redirect Service]
- Read-heavy path
- Redirect latency target applies
- Must remain independent from analytics completion

[(Link Store)]
- Authoritative mapping data
- Durability requirement applies
- Regional data constraint applies

[[Redirect Events]]
- Duplicate-tolerant consumer required
- Backlog monitoring required

Use requirement identifiers where possible:

[Redirect Service]
Supports: FR-02, FR-04, FR-06
Quality: NFR-PERF-01, NFR-AVAIL-01

[(Link Store)]
Supports: FR-01, FR-02
Quality: NFR-DUR-01
Constraint: CON-DATA-01

Observability in High-Level Diagrams

Logs, metrics and traces can be represented as one cross-cutting observability capability unless the architecture requires more detail.

[Gateway] --------+
                  |
[Link Service] ---+----> [Observability Platform]
                  |
[Redirect Service]+
                  |
[Worker] ---------+

Signals:
- Request rate and latency
- Failure rate
- Cache hit ratio
- Queue backlog
- Database errors
- End-to-end trace context

High-Level Diagram Creation Process

1. Define the diagram's audience and purpose.
2. Confirm the system boundary.
3. List external actors and dependencies.
4. Select the important functional requirements.
5. Review the major request flows.
6. Identify major responsibilities.
7. Group responsibilities into logical components.
8. Identify authoritative and derived data stores.
9. Identify synchronous and asynchronous connections.
10. Add trust, ownership or deployment boundaries where relevant.
11. Label important connections.
12. Trace successful and failure paths.
13. Review the diagram against non-functional requirements and constraints.
14. Remove implementation detail that does not support the diagram's purpose.
15. Add a title, scope, legend, version and unresolved decisions.

Diagram Review Checklist

Common High-Level Diagram Mistakes

Diagram Documentation Template

Diagram title:
<Descriptive architecture view name>

Diagram ID:
HLD-<number>

Purpose:
<Question answered by this diagram>

Scope:
<System, feature or workflow included>

Audience:
<Reviewers who should use this view>

Related requirements:
<Requirement identifiers>

Related constraints:
<Constraint identifiers>

Included components:
<Major actors, services, data stores and dependencies>

Excluded details:
<Implementation or deployment information intentionally omitted>

Notation:
<Meaning of shapes, lines, colors and boundaries>

Key flows:
<Important request or event flows visible in the diagram>

Important decisions:
<Architecture choices represented>

Open questions:
<Decisions that remain unresolved>

Version:
<Diagram version>

Status:
Draft / Reviewed / Approved / Superseded

Practice Exercise

Create high-level diagrams for a notification platform that supports email, SMS and mobile push notifications.

Required Views

1. Create a context diagram showing clients and external delivery providers.
2. Create a component diagram showing the API, store, queue and workers.
3. Create a sequence diagram for submitting a notification.
4. Create a sequence diagram for asynchronous delivery.
5. Create a failure view for a temporary provider outage.
6. Identify trust boundaries.
7. Label synchronous and asynchronous connections.
8. Link major components to requirements and constraints.

Model Component Diagram

                        [Identity Provider]
                                  |
                                  v
[Client] ---> [Notification API] ---> [(Notification Store)]
                      |
                      | Accepted delivery command
                      v
               [[Delivery Queue]]
                      |
          +-----------+-----------+
          |           |           |
          v           v           v
   [Email Worker] [SMS Worker] [Push Worker]
          |           |           |
          v           v           v
   [Email Provider] [SMS Provider] [Push Provider]
          |           |           |
          +-----------+-----------+
                      |
                      v
             [(Delivery Status)]

Review Questions

• Is the identity provider inside or outside the owned boundary?
• Which component owns notification status?
• Does one queue serve every channel?
• How is channel-specific retry behaviour represented?
• What happens when a provider is unavailable?
• How does the caller retrieve final status?
• Where are templates stored and rendered?
• Which components handle sensitive recipient information?
• Which signals detect growing delivery backlog?
• What must be changed if data residency differs by region?

Frequently Asked Questions