Request & Information Flow

Runtime flow

flowchart TD
    R[Request received]
    P[Identify endpoint policy]
    N[Normalise relevant request inputs]
    C{Reusable response available?}
    H[Return cached response]
    O[Forward to authoritative backend]
    S{Response suitable for reuse?}
    W[Store with bounded freshness]
    X[Return response]

    R --> P
    P --> N
    N --> C
    C -- Yes --> H
    C -- No / bypass --> O
    O --> S
    S -- Yes --> W
    S -- No --> X
    W --> X

Request identity

Two requests that are semantically equivalent should resolve to the same cache identity.

That means request identity cannot rely blindly on raw query-string order. Relevant inputs need to be normalised so equivalent requests do not create duplicate cache entries.

This is an architectural concern because poor identity design undermines both efficiency and correctness.

Freshness

A cached response is only useful while it remains acceptable for reuse.

The design therefore treats freshness as policy rather than a single global timeout. Different endpoint types can have different lifetimes according to how quickly their underlying information changes and how much staleness is acceptable.

Response suitability

Not every response should be cached.

The proxy evaluates whether the request/response combination is suitable for reuse before storing it. This prevents the architecture from turning caching into an indiscriminate default.

Information ownership

The information model is intentionally simple:

• the backend owns authoritative business information;
• the edge holds temporary delivery copies;
• policy configuration describes how delivery copies may be reused;
• the consuming application remains unaware of the cache implementation.

That separation prevents the cache from becoming an accidental second system of record.