Document the request lifecycle and middleware execution order from app.js bootstrap

[mikewheeleer]

Document the end-to-end middleware execution order

Description

A request to the Liquifact API passes through a long, order-sensitive middleware chain assembled in src/app.js and the composed stacks in src/middleware/stacks.js: correlation/request id, sanitization, body-size limits, CORS, helmet security headers, rate limiting, authentication, tenant extraction, KYC and legal-hold gates, idempotency, then route handlers, and finally the RFC 7807 error handler. The exact order is load-bearing (e.g. sanitization before validation, auth before tenant, gates before the funding handler), but docs/request-lifecycle-middleware-order.md does not yet reflect the current bootstrap. This issue produces an authoritative, code-accurate description.

Requirements and context

• Repository scope: Liquifact/Liquifact-backend only.
• Enumerate the actual global and per-stack middleware order as wired in src/app.js and src/middleware/stacks.js, explaining why each ordering constraint matters (e.g. sanitization before src/utils/validators.js, requireKycForFunding and legalHoldGate before submission in src/routes/invest.js).
• Include a Mermaid sequence diagram of a representative POST /api/invest/fund-invoice request from id assignment to error mapping in src/middleware/problemJson.js.
• Cross-reference the body-size limits, CORS, helmet, and rate-limit middlewares and which routes opt into stricter stacks.
• Ensure middleware names and order in the doc match the code exactly by inspection.

Suggested execution

• Fork the repo and create a branch
• git checkout -b docs/request-lifecycle-16-middleware-order
• Implement changes
  • Write code in: docs-only; no runtime change unless an undocumented/misordered middleware is found.
  • Write comprehensive tests in: n/a; optionally add a route-order assertion test in tests/app.routes.test.js if a mismatch is found.
  • Add documentation: rewrite docs/request-lifecycle-middleware-order.md and link it from README.md.
  • Ensure middleware labels match the constants/exports in app.js/stacks.js.
  • Validate security: clearly call out the security-critical ordering invariants (auth→tenant, gates→handler, sanitize→validate).
• Test and commit

Test and commit

• Run npm run lint to confirm no code regressions.
• Cover edge cases in prose: an unauthenticated request, a request blocked at the KYC/legal-hold gate, and an error mapped by the 7807 handler.
• Include the rendered diagram in the PR description.

Example commit message

docs(request-lifecycle): document the middleware execution order from app bootstrap

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the Liquifact community on Discord for questions, reviews, and faster merges: https://discord.gg/JrGPH4V3
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.

[silentgeckoaudit3801]

I would like to work on this. I'll keep it docs-only, match the order in src/app.js and src/middleware/stacks.js by inspection, and wait for assignment or maintainer confirmation before opening a PR.

[CyrusAuyeung]

Hi maintainers, is this issue still available for a new PR?

I see no linked PR for #520 and no current assignee. There is one prior contributor comment saying they will wait for assignment or maintainer confirmation, so I do not want to duplicate assigned work.

If it is available, I can keep the change docs-focused and code-accurate: inspect src/app.js and src/middleware/stacks.js, update docs/request-lifecycle-middleware-order.md, cross-link from README.md, include the requested Mermaid sequence diagram, and avoid runtime changes unless inspection reveals a real mismatch. I will wait for maintainer or Wave/GrantFox confirmation before opening a PR.