The "Onion Rule" of Frontend Architecture: Why Your Interceptor Order Is Secretly Breaking Your UX

Recently, while designing the core network layer for a production Angular application, we encountered a subtle bug. When a user opened a page that fired three parallel API calls (forkJoin) while their short-lived access token was expired, the application did something strange:

1. It successfully refreshed the token in the background.
2. Yet it still popped up three error dialogs on the screen.

Fixing it didn't require rewriting a single line of RxJS inside our services or components. It required swapping two words in app.config.ts:

// Before
withInterceptors([authInterceptor, errorInterceptor])
// After
withInterceptors([errorInterceptor, authInterceptor])

1. What Is an Interceptor—and Why Do Enterprise Apps Need Them?
In a small prototype, a component calls http.get('/api/data'), passes a header, and writes a catchError block to show a toast message.

Now scale that to an enterprise platform with 80 components, 150 endpoints, role-based access control (RBAC), silent token rotation, and retry policies. If every service or component handles its own authentication, retries, and error popups:

• You violate DRY (Don't Repeat Yourself): Boilerplate error-handling code is duplicated hundreds of times.
• You violate SRP (Single Responsibility Principle): Feature services now care about token expiration and modal dialogs instead of business data.
• You create race conditions: When 4 parallel requests fail at the same millisecond, 4 independent error handlers fight over the UI.

An HTTP Interceptor solves this by sitting in the middle of the HTTP client pipeline. It intercepts every outbound HttpRequest before it touches the browser's network stack and inspects every inbound HttpResponse (or HttpErrorResponse) before your services ever receive it.

2. The Mental Trap: Linear vs. Onion Execution
The most common misconception in frontend engineering is that an array of interceptors [A, B, C] executes linearly from A -> B -> C for both requests and responses.

It does not.

Every modern interceptor pipeline—whether in Angular, Axios, or backend middleware the Onion Model (also known as the Russian Doll pattern). Each interceptor wraps the next() handler inside its own observable stream.

Notice the two directions:

• Outbound (The Request Phase): Flows Left-to-Right (Index 0 -> Index 1 -> Network).
• Inbound (The Response/Error Phase): Flows Right-to-Left (Network -> Index 1 -> Index 0).The last interceptor to touch the request on the way out is the first interceptor to touch the response on the way back.

3. Anatomy of a Production Bug: [auth, error] vs. [error, auth]
Let’s trace what happens when a component fires three parallel catalog requests (geos, flows, payment-types) using forkJoin, and the user's JWT cookie has expired (401 Unauthorized).

Scenario A: The Wrong Order ([authInterceptor, errorInterceptor])
Here, errorInterceptor is at Index 1 meaning it is the innermost ring closest to the network.

1. All 3 requests hit the backend and return 401 Unauthorized.
2. Because errorInterceptor is closest to the network, it catches the 401 first.
3. It reads the custom fallback error context for each of the 3 endpoints and immediately opens 3 error modals on the screen.
4. It rethrows the error outward to authInterceptor (Index 0), which then refreshes the token—way too late to save the user experience.

Scenario B: The Architect's Order ([errorInterceptor, authInterceptor])
Now we swap them. authInterceptor is at Index 1 the innermost ring guarding the network boundary.

1. All 3 requests return 401 Unauthorized from the network.
2. authInterceptor catches them first. The UI layer (errorInterceptor) has no idea anything went wrong.
3. authInterceptor pauses the failed requests, calls /auth/refresh once, gets a 200 OK with fresh credentials, and seamlessly replays the 3 requests.
4. The replayed requests return 200 OK and pass straight through errorInterceptor to the component. Zero popups. Zero user friction.
5. What if the user's account is genuinely deactivated and /refresh (or the retry) still fails? Only then does authInterceptor throw the unrecoverable error outward to errorInterceptor, which deduplicates the identical error signature in a Map and shows one clean modal.

4. When & How to Bypass the Onion (HttpContext Tokens)
A rigid global pipeline is dangerous if individual endpoints cannot opt out. For example:

• What happens when the /login endpoint itself returns 401 because the user typed the wrong password? You don't want authInterceptor trying to refresh a token on /login, and you don't want errorInterceptor launching a global system crash modal for a simple typo.
• What happens when uploading a binary file directly to an S3 presigned URL? Attaching your internal Authorization header will cause S3 to reject the request.

In modern Angular, never hardcode URL string checks (if (req.url.includes('/login'))) inside interceptors. Instead, use strongly-typed HttpContextToken flags:

This respects the Open/Closed Principle (SOLID). Your interceptors remain generic, while specific service calls can selectively disable layers of the onion:

5. Making the Onion Rule Survive People: Self-Sorting Layer Priorities
Swapping two items in app.config.ts fixed the bug today. Any experienced architect should still feel uneasy about how it was fixed.

When the correctness of your entire authentication and error-handling pipeline depends on the order of an array literal, you have an unwritten contract. Unwritten contracts do not survive team growth. Six months from now, a developer will add a fourth interceptor—a telemetry logger or a client cache—and drop it at the end of withInterceptors([...]) without realizing they just pushed authInterceptor out of the innermost ring. Even if you leave a giant comment above the array, comments drift long before code does.

To make the Onion Rule survive people, the array literal cannot be the source of truth.

Instead of trusting developers to remember array positions, we encode each ring of the onion as an explicit priority rank (InterceptorLayer) and force the pipeline to sort itself at registration time.

Step 1: Define the Architectural Rings as Stepped Constants
We define an InterceptorLayer enum ordered from the Outermost Ring (Closest to the UI = 10) to the Innermost Ring (Closest to the Network Wire = 40). Using stepped increments of 10 leaves room to insert future middleware (like a rate-limiter at 25) without renumbering existing layers:

import { HttpInterceptorFn } from '@angular/common/http';

export enum InterceptorLayer {
UI_ERROR = 10, // Outer Ring: Global UI Error Modals & Spinners
CLIENT_CACHE = 20, // Ring 2: IndexedDB & In-Flight Deduplication
TELEMETRY = 30, // Ring 3: Trace IDs & Performance Logging
AUTH_NETWORK = 40, // Inner Airlock: Credentials & Silent 401 Refresh
}

export interface InterceptorMetadata {
readonly id: string;
readonly layer: InterceptorLayer;
}

export type RankedInterceptorFn = HttpInterceptorFn & InterceptorMetadata;

export function createLayeredInterceptor(
metadata: InterceptorMetadata,
interceptorFn: HttpInterceptorFn
): RankedInterceptorFn {
return Object.assign(interceptorFn, metadata);
}

export function resolveInterceptorPipeline(
interceptors: readonly RankedInterceptorFn[]
): HttpInterceptorFn[] {
return [...interceptors].sort((a, b) => a.layer - b.layer);
}

Step 2: Tag Each Interceptor With Its Ring
Because functions are first-class objects in JavaScript, createLayeredInterceptor attaches the layer metadata directly onto the HttpInterceptorFn without changing Angular's functional interceptor signature:

// error.interceptor.ts — Locked to the Outer UI Ring (10)
export const errorInterceptor = createLayeredInterceptor(
{ id: 'errorInterceptor', layer: InterceptorLayer.UI_ERROR },
(req, next) => { /* ... */ }
);

// auth.interceptor.ts — Locked to the Inner Network Airlock (40)
export const authInterceptor = createLayeredInterceptor(
{ id: 'authInterceptor', layer: InterceptorLayer.AUTH_NETWORK },
(req, next) => { /* ... */ }
);

Step 3: Self-Sorting Registration + A CI/CD Guardrail Test
Now look at what happens in app.config.ts:
export const REGISTERED_INTERCEPTORS = resolveInterceptorPipeline([
authInterceptor, // Layer 40 (intentionally listed first)
errorInterceptor, // Layer 10
]);

// Inside appConfig providers:
provideHttpClient(
withFetch(),
withInterceptors(REGISTERED_INTERCEPTORS) // Always resolves to [error (10), auth (40)]
)

This gives our architecture three permanent safety nets:

• Compile-Time Enforcement: resolveInterceptorPipeline() only accepts RankedInterceptorFn[]. If a developer writes a raw HttpInterceptorFn without declaring which ring of the onion it belongs to, TypeScript refuses to compile.
• Runtime Self-Healing: Even if a merge conflict or a developer scrambles the array order in app.config.ts, sort((a, b) => a.layer - b.layer) guarantees the exact same runtime execution order every time the app boots.
• CI/CD Contract Verification: We back the registration constant with a 5-line unit test asserting that errorInterceptor always precedes authInterceptor in REGISTERED_INTERCEPTORS.

6. The Frontend Architect's Checklist for Interceptor Design
Whenever you are setting up or auditing the HTTP layer of an enterprise application, apply these four rules:

i. Order from UI-Inward to Network-Outward(10 -> 40):
Place UI-facing interceptors (Global Error Modals, Loading Spinners) at the beginning of the array (Index 0), and network-recovery interceptors (Auth, Token Refresh, Retry) at the end of the array (Index N).

ii. Make the Order Self-Sorting: Don't rely on array position or code comments. Tag interceptors with an InterceptorLayer priority enum and sort them deterministically at startup.

iii. Deduplicate 401 Refreshes & UI Error Modals:
When forkJoin fires 3 parallel requests and the token is expired, all 3 401 responses must share a single in-flight /refresh stream (shareReplay + finalize cleanup) rather than hammering the auth server 3 times. And if the network drops completely, deduplicate active error dialogs in a Map keyed by ${title}||${message} so the user only sees one modal.

iv. Use HttpContext Instead of URL Matching:
Let the calling service declare its intent via HttpContextToken rather than polluting interceptors with fragile regex or .includes() checks.

v. Never Mutate Requests Directly:
Always use req.clone() to preserve immutability across retries and post-refresh replays.

Architecture isn't about making code look complicated. It's about putting boundaries in the exact right order so complex failures look effortless to the user.