Introduction

A request flow describes the complete journey of a request, command, event or transaction through a system.

A high-level architecture diagram shows which components exist. A request flow explains how those components work together to complete a particular user operation.

For example, a request flow can explain:

• How a user creates a short URL
• How a visitor is redirected to the destination URL
• How an order is placed and confirmed
• How a file is uploaded and processed
• How a notification is accepted and delivered
• How a search query produces ranked results

In the System Design curriculum, request flow is Topic 1.4 under System Design Process and Estimation. It follows requirements discovery, functional and non-functional requirements, and constraints. The module uses these inputs to develop a repeatable design process before selecting detailed components.

Prerequisites

What Is a Request Flow?

A request flow is an ordered description of the components and processing steps involved in handling one request from initiation to completion.

A useful request flow identifies:

• The actor initiating the operation
• The request protocol and endpoint
• The system entry point
• Authentication and authorization checks
• Input validation
• Business-rule execution
• Cache, database or external-system access
• State changes
• Messages or events produced
• The response returned to the caller
• Timeout, retry and failure behaviour
• Logs, metrics and traces generated

Request Flow vs Architecture Diagram

Common Request-flow Layers

A real flow does not have to contain every layer. Add a component only when a requirement, constraint or verified design need justifies it.

Synchronous Request Flow

In a synchronous flow, the caller waits while the system performs the required work and produces a response.

Client
  |
  | 1. Send request
  v
API Entry Point
  |
  | 2. Authenticate and validate
  v
Application Service
  |
  | 3. Read or change data
  v
Database
  |
  | 4. Return result
  v
Application Service
  |
  | 5. Build response
  v
Client

Synchronous processing is commonly appropriate when:

• The caller needs the final result immediately
• The work can finish within the response-time target
• The dependency chain is reasonably controlled
• The caller must know whether the operation succeeded

Synchronous-flow Risk

Every required dependency in the synchronous path can contribute latency and failure. A chain of synchronous calls may therefore increase the probability that the user-facing operation cannot complete.

Asynchronous Request Flow

In an asynchronous flow, the system accepts work and processes all or part of it separately from the original request.

Client
  |
  | 1. Submit request
  v
API Service
  |
  | 2. Validate and record accepted work
  v
Queue or Stream
  |
  | 3. Return accepted response
  v
Client

Queue or Stream
  |
  | 4. Deliver work
  v
Worker
  |
  | 5. Perform processing
  v
Database or External Provider
  |
  | 6. Record final status
  v
Status Store / Notification

Asynchronous processing is commonly considered when:

• The work may take longer than the request timeout
• The user does not need the final result immediately
• Load must be buffered
• Work should continue after the client disconnects
• A dependency is slow or temporarily unavailable
• Retry and delayed processing are required

Synchronous vs Asynchronous Flow

Read Request Flow

A read flow retrieves data without intentionally changing the primary business state.

Cache-hit Flow

Client
  |
  v
Load Balancer / Gateway
  |
  v
Application Service
  |
  | Lookup key
  v
Cache
  |
  | Value found
  v
Application Service
  |
  v
Client

Cache-miss Flow

Client
  |
  v
Application Service
  |
  | 1. Lookup key
  v
Cache
  |
  | 2. Miss
  v
Application Service
  |
  | 3. Query durable store
  v
Database
  |
  | 4. Return record
  v
Application Service
  |
  | 5. Populate cache
  v
Cache
  |
  | 6. Return response
  v
Client

A read-flow review should ask:

• Is the requested data cacheable?
• How stale may the cached value be?
• What happens when the cache is unavailable?
• Can concurrent misses overload the database?
• Which store is authoritative?
• Can stale data violate a business rule?
• How are missing and deleted records represented?

Write Request Flow

A write flow creates, modifies or deletes business state.

Client
  |
  | 1. Submit command
  v
API Gateway
  |
  | 2. Authenticate and authorize
  v
Application Service
  |
  | 3. Validate request
  | 4. Check business rules
  v
Database
  |
  | 5. Commit state
  v
Application Service
  |
  | 6. Invalidate or update cache
  | 7. Publish required event
  v
Client Response

A write-flow review should ask:

• Which validation occurs before storage access?
• Which state changes must occur atomically?
• What happens when a duplicate request arrives?
• When is the operation considered committed?
• How are caches updated or invalidated?
• How are downstream events published?
• What happens when storage succeeds but event publication fails?
• What result is returned after an uncertain timeout?

Authentication and Authorization in the Flow

Authentication establishes the caller's identity. Authorization determines whether that identity may perform the requested action.

Request
  |
  v
Token or Session Validation
  |
  +-- Invalid identity --------> Reject
  |
  v
Authorization Check
  |
  +-- Insufficient permission -> Reject
  |
  v
Business Operation

Identity checks should be placed where the system can enforce the required trust boundary. Business-resource authorization may also require data known only by the application service.

Validation Flow

Validation should occur before an invalid request causes expensive work or changes state.

Complete Example: URL Shortener

Create-link Flow

User
  |
  | POST /links
  | Destination URL
  | Optional alias and expiration
  v
Edge / API Entry Point
  |
  | Apply request-size and abuse controls
  v
Link Service
  |
  | Validate URL
  | Authenticate if owner features are requested
  | Check alias rules
  v
Identifier Generator
  |
  | Generate unique short code
  v
Link Database
  |
  | Store mapping
  v
Link Service
  |
  | Return short URL
  | Publish optional analytics or audit event
  v
User

Create-link Steps

1. The client submits a destination URL and optional settings.
2. The entry layer applies applicable request and abuse controls.
3. The link service validates the destination and request fields.
4. The service verifies ownership permissions when account-specific functionality is requested.
5. The system generates or validates a short code.
6. The mapping is written to the authoritative store.
7. Optional secondary work is initiated according to its consistency requirements.
8. The service returns the short URL or a descriptive error.

Redirect Flow

Visitor
  |
  | GET /{short-code}
  v
DNS / Edge
  |
  v
Load Balancer
  |
  v
Redirect Service
  |
  | Lookup short code
  v
Cache
  |
  +-- Hit ----------------------+
  |                             |
  +-- Miss --> Link Database    |
                 |              |
                 +--> Mapping --+
                                |
                                v
                     Validate status and expiry
                                |
                    +-----------+-----------+
                    |                       |
                 Valid                   Invalid
                    |                       |
                    v                       v
              Redirect response      Error response
                    |
                    v
             Analytics event
             when required

Redirect-flow Questions

• What happens when the short code is unknown?
• How quickly must a deactivated link stop redirecting?
• Can a cached mapping remain after deactivation?
• Should analytics failure block the redirect?
• What happens when the cache is unavailable?
• What happens when the database is unavailable?
• Can the destination URL be modified after creation?
• Which status code is returned for expired links?
• How are malicious destinations blocked?

Failure Request Flow

A request flow is incomplete if it describes only the successful path. Failure flows reveal where architecture decisions are required.

Cache Failure

Redirect request
  |
  v
Cache lookup
  |
  +-- Cache available --> Normal lookup
  |
  +-- Cache unavailable
          |
          +-- Use authoritative store when allowed
          |
          +-- Return controlled failure when fallback is unsafe
          |
          +-- Emit failure metric and diagnostic trace

Database Timeout

Service sends database request
  |
  v
Timeout occurs
  |
  +-- Read operation:
  |      Retry only when policy and remaining deadline permit
  |
  +-- Write operation:
         Determine whether the result is known or uncertain
         Avoid duplicate state changes
         Use idempotency or status reconciliation where required

Queue Publication Failure

Business state committed
  |
  v
Event publication fails
  |
  +-- Unsafe design:
  |      State exists but required event may be lost
  |
  +-- Reliability pattern:
         Record state and publication intent consistently
         Publish later through a recoverable process

Timeout Budget

A request has a limited time in which it can complete. Each synchronous dependency consumes part of that time.

A simplified latency relationship is:

\[ T_{total} = T_{network} + T_{queue} + T_{application} + T_{dependencies} + T_{serialization} \]

For sequential dependencies:

\[ T_{dependencies} = T_{dependency1} + T_{dependency2} + \cdots + T_{dependencyN} \]

In practice, queuing, contention, retries and network variability can increase end-to-end latency. The request-flow document should therefore identify every dependency in the critical synchronous path.

Retries

A retry creates another attempt after a failure or timeout. Retrying is not automatically safe.

Retry Questions

• Is the failure temporary?
• Is enough request deadline remaining?
• Is the operation safe to repeat?
• Could the previous attempt have succeeded?
• Will retries increase overload?
• Which layer owns the retry?
• How many attempts are permitted?
• How will repeated failures be observed?

Client retries
Gateway retries
Service retries
Worker retries
SDK retries

When several layers retry independently, one original request can create many downstream attempts.

Retry owner:
Application service

Retry conditions:
Only selected temporary failures

Maximum attempts:
Defined by policy

Delay:
Backoff with controlled randomness

Safety:
Operation is idempotent or protected by an idempotency key

Deadline:
Retry only while sufficient time remains

Idempotency

An idempotent operation can be repeated without creating unintended additional business effects.

Example

Without idempotency:
Client submits order.
Service creates order.
Response is lost.
Client retries.
Service creates a second order.

With idempotency:
Client submits order with key K.
Service creates order and associates result with K.
Response is lost.
Client retries with key K.
Service returns the previously recorded result.

Idempotency does not mean that every repeated response must be generated without processing. It means the repeated operation does not create an unintended duplicate business effect under the defined contract.

Parallel Request Flow

Independent operations can sometimes be executed in parallel rather than sequentially.

Application Service
  |
  +------> Profile Service ------+
  |                              |
  +------> Preference Service ---+--> Combine results
  |                              |
  +------> Recommendation -------+

A parallel flow should define:

• Whether every result is required
• The timeout for each dependency
• What happens when only one call fails
• Whether partial results are acceptable
• How the results are combined
• Whether cancellation is propagated

Fan-out and Fan-in

Fan-out occurs when one request produces several downstream operations. Fan-in occurs when their results are collected.

One request
    |
    +-- Operation A
    +-- Operation B
    +-- Operation C
    |
    v
Combine results
    |
    v
One response

Fan-out can reduce elapsed time when work is independent, but it also increases downstream load and introduces partial-failure decisions.

Event Flow

A request flow follows a direct operation initiated by a caller. An event flow follows a published fact that can be processed by one or more consumers.

Order Service
  |
  | OrderCreated event
  v
Event Stream
  |
  +------> Inventory Consumer
  |
  +------> Notification Consumer
  |
  +------> Analytics Consumer

An event-flow design should document:

• The event producer
• The event meaning
• Schema and version
• Partition or ordering key
• Consumers
• Duplicate-handling rules
• Retry and dead-letter behaviour
• Retention
• Reprocessing behaviour

Observability in Request Flow

A production request should generate enough evidence to determine where time was spent and where a failure occurred.

Correlation Context

Client request ID
        |
        v
Gateway request ID
        |
        v
Application trace context
        |
        +--> Database span
        |
        +--> Cache span
        |
        +--> External-provider span
        |
        +--> Published event metadata

Correlation identifiers should support diagnosis without exposing secrets or sensitive user data.

Request-flow Documentation Template

Flow ID:
FLOW-<number>

Name:
<Short operation name>

Related requirements:
<Requirement IDs>

Primary actor:
<Client, user or external service>

Trigger:
<Request or event that starts the flow>

Preconditions:
<Conditions that must already be true>

Input:
<Important fields, headers or payload>

Entry point:
<Endpoint, topic, job or interface>

Main flow:
1. <First processing step>
2. <Second processing step>
3. <State read or update>
4. <Response or event>

Data accessed:
<Caches, databases, files or external systems>

State changed:
<Durable or temporary state changes>

Output:
<Response, status, file or event>

Timeouts:
<Relevant request and dependency timeouts>

Retry policy:
<Owner, conditions and maximum attempts>

Idempotency:
<How duplicates are detected or prevented>

Failure paths:
<Validation, dependency, storage and timeout failures>

Observability:
<Logs, metrics, traces and audit evidence>

Security:
<Authentication, authorization and data controls>

Request-flow Review Questions

Common Request-flow Mistakes

Practice Exercise

Design the request flows for a notification service that sends email, SMS and mobile push notifications.

Required Flows

1. Submit a notification request.
2. Validate the recipient and template.
3. Accept the request for asynchronous processing.
4. Deliver through the selected provider.
5. Record the delivery result.
6. Retry a temporary provider failure.
7. Move an exhausted request to a failure-handling path.
8. Retrieve notification status.

Model High-level Flow

Client
  |
  | Submit notification
  v
Notification API
  |
  | Authenticate
  | Validate request and template
  | Check idempotency key
  v
Notification Store
  |
  | Record accepted notification
  v
Delivery Queue
  |
  | Return accepted status
  v
Client

Delivery Queue
  |
  v
Channel Worker
  |
  | Build provider-specific request
  v
Email / SMS / Push Provider
  |
  +-- Success --> Record delivered status
  |
  +-- Temporary failure --> Retry according to policy
  |
  +-- Permanent failure --> Record failed status
  |
  +-- Attempts exhausted --> Dead-letter or review path

Questions to Answer

• When is a notification considered accepted?
• When is it considered delivered?
• How are duplicate submissions handled?
• Which failures are retryable?
• How is retry delay controlled?
• Does one channel failure affect another channel?
• How can the caller retrieve final status?
• Which identifiers connect API, queue and provider activity?
• What data may appear in logs?
• How is accumulated queue backlog detected?

Frequently Asked Questions