HTTP request lifecycle

Question and use cases

The complete middleware order from trusted proxy data to endpoint dispatch.

Use this flow before inserting middleware or diagnosing a request that fails at the wrong stage.

Use the diagram during design review, incident diagnosis, code walkthroughs, and onboarding. It intentionally omits classes and projects unrelated to the focused question, so read it together with the source entry point and related topic pages.

This page covers only the named responsibilities and relationships; consult the relevant module documentation for capabilities not shown here.

Reading path

1. Step 1: Follow the numbered phases from outer infrastructure handling to endpoint dispatch.
2. Step 2: Within a phase, read left to right and note which context becomes available.
3. Step 3: Compare cache, quota, tenant, audit, and timeout positions because order changes semantics.

Do not skip arrow direction, numbering, or group titles: they express dependency or time direction, execution order, and responsibility boundaries. If the diagram differs from current source or accepted architecture decisions, correct the generated catalog immediately.

Legend and notation

This is a REQUEST FLOW diagram. Use that form to understand the layout, then test your interpretation against the source facts below.

Key relationships and design meaning

Relationship 1

Source fact: Forwarded headers and exception handling are outermost; endpoint dispatch is last.

Architectural meaning: Outer middleware establishes trusted transport and failure handling before application security or context resolution runs.

Review action: Is trusted proxy information established before security decisions use it?

Relationship 2

Source fact: Delegation validation precedes tenant resolution, while tenant impersonation validation follows it.

Architectural meaning: Resolving delegation before tenant context, then validating impersonation after it, gives each check the context it actually needs.

Review action: Can a cache hit bypass rate limiting or request audit?

Relationship 3

Source fact: Rate limiting precedes output cache so a cache hit cannot bypass quota enforcement.

Architectural meaning: Quota enforcement before output caching ensures an inexpensive cached response still consumes the caller’s configured allowance.

Review action: Does endpoint code receive authenticated tenant and trace context?

Design review questions

Answer each question when reviewing or implementing a related change. If code, tests, or an ADR cannot support the answer, do not decide from the diagram alone.

• Is trusted proxy information established before security decisions use it?
• Can a cache hit bypass rate limiting or request audit?
• Does endpoint code receive authenticated tenant and trace context?

How to use the answers

1. Identify the single owner of the capability or rule.
2. Confirm that dependency, call, or event direction does not reverse ownership.
3. Capture the conclusion with an automated test or repeatable command.

Boundaries and common mistakes

Boundary 1

Middleware order is behavior: moving one stage can change security, caching, audit, or timeout semantics.

• Do not infer: A connector in the diagram does not mean every implementation uses synchronous calls, a shared transaction, or shared data ownership.
• Review requirement: Can a cache hit bypass rate limiting or request audit?

Boundary 2

Read the diagram left-to-right within each numbered phase, then continue to the next phase.

• Do not infer: A connector in the diagram does not mean every implementation uses synchronous calls, a shared transaction, or shared data ownership.
• Review requirement: Does endpoint code receive authenticated tenant and trace context?

Source verification and regeneration

The primary verification entry point is src/Hosts/BitzOrcas.Api/Program.cs. Inspect it and its direct references before regenerating diagram assets and pages.

# Regenerate bilingual SVG, standalone HTML, and documentation pages
npm run diagrams

# Check locale pairs, references, safety attributes, accessibility, and canvas bounds
npm run verify:diagrams

# Confirm that generation changed only the intended diagrams and pages
git diff -- scripts/diagrams diagram-sources public/diagrams src/content/docs

# Verify internal links, MDX structure, and professional depth gates
npm run verify:docs
npm run audit:docs-depth

Change-completion checklist

• Responsibilities, order, states, and relationships match current source.
• Every new element helps answer this page’s question instead of turning the diagram into an inventory.
• Arrows have explicit direction and semantics without implying nonexistent synchronous or transactional guarantees.
• Chinese and English titles, labels, facts, and boundaries remain semantically equivalent.
• The diagram remains readable on narrow screens, in fullscreen, and while zoomed, with no overlap or overflow.
• Relevant architecture tests, integration tests, or verification commands have run.
• If a long-lived constraint changed, its ADR or architecture documentation is updated.

Continue reading

• Architecture overview
• All architecture diagrams
• Platform modules