Document the middleware pipeline and request lifecycle
Description
The app factory in src/app.js composes a specific middleware order (CORS, body-size guardrails, security headers, audit, routes, 404, then CORS/payload/error handlers) and re-usable stacks live in src/middleware/stacks.js (authenticatedTenantStack, adminStack). Contributors have no single document explaining the ordering, why it matters (e.g. sanitization before validation, KYC before legal-hold), or how a request flows through to a route. This issue documents the full pipeline.
Requirements and context
- Repository scope: Liquifact/Liquifact-backend only.
- Document the exact middleware order in
src/app.js and the composed stacks in src/middleware/stacks.js, explaining the security rationale for each position (correlation id, sanitize, auth, tenant, KYC, legal-hold, rate limit).
- Include a request-lifecycle diagram (Mermaid) from ingress through response/error handling, referencing
src/middleware/errorHandler.js and src/middleware/problemJson.js.
- Cross-link the standardized envelope (
src/utils/responseHelper.js) and the RFC 7807 error model.
- Ensure the described order matches the code exactly (verify by inspection).
Suggested execution
- Fork the repo and create a branch
git checkout -b docs/architecture-39-request-lifecycle- Implement changes
- Write code in: docs-only; no runtime change unless an ordering bug is found.
- Write comprehensive tests in: n/a (verify order matches code); optionally reference
tests/app.routes.test.js.
- Add documentation: add
docs/request-lifecycle.md and link it from README.md and CONTRIBUTING.md.
- Ensure middleware names match the code exactly.
- Validate security: rationale for security-ordering positions is accurate.
- Test and commit
Test and commit
- Run
npm run lint to confirm no code regressions.
- Cover edge cases in prose: sanitize-before-validate, KYC-before-legal-hold, error vs 404 handling order.
- Include the rendered diagram in the PR description.
Example commit message
docs(architecture): document middleware order and request lifecycle
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.
Document the middleware pipeline and request lifecycle
Description
The app factory in
src/app.jscomposes a specific middleware order (CORS, body-size guardrails, security headers, audit, routes, 404, then CORS/payload/error handlers) and re-usable stacks live insrc/middleware/stacks.js(authenticatedTenantStack,adminStack). Contributors have no single document explaining the ordering, why it matters (e.g. sanitization before validation, KYC before legal-hold), or how a request flows through to a route. This issue documents the full pipeline.Requirements and context
src/app.jsand the composed stacks insrc/middleware/stacks.js, explaining the security rationale for each position (correlation id, sanitize, auth, tenant, KYC, legal-hold, rate limit).src/middleware/errorHandler.jsandsrc/middleware/problemJson.js.src/utils/responseHelper.js) and the RFC 7807 error model.Suggested execution
git checkout -b docs/architecture-39-request-lifecycletests/app.routes.test.js.docs/request-lifecycle.mdand link it fromREADME.mdandCONTRIBUTING.md.Test and commit
npm run lintto confirm no code regressions.Example commit message
docs(architecture): document middleware order and request lifecycleGuidelines
Community & contribution rewards