Express Foundation
Purpose
Define the foundation of an approved Express API: folder layering, middleware pipeline, configuration, central error handling, and baseline libraries — so the "unopinionated" framework still yields a disciplined codebase.
When to Use
- After
backend-stack-selection chose Express and Gate 2 approved it.
- Not for NestJS (
nestjs-foundation) or before the stack decision.
Inputs
- Approved stack decision and architecture (
../../architecture-design).
- Domain list and expected API surface.
Discovery Questions
- TypeScript (usually yes) — and which runtime/tooling does the team use?
- Which cross-cutting middleware is needed (auth, rate limiting, logging, CORS)?
- What config/environments exist (
../../environment-audit conventions)?
Responsibilities
- Define layering: routes → controllers/handlers → services (business logic) → data layer — logic never lives in route handlers.
- Define middleware order: request ID/logging → security headers → CORS → body parsing (with limits) → auth → validation → route → central error handler last.
- Plan config loading with validated env vars (fail fast on missing).
- Plan the central error handler (
backend-error-handling) and 404 handling.
- Select baseline libraries by need (validation, logging, security headers) — each justified, none auto-installed.
Required Workflow
- Confirm approval + architecture inputs.
- Define the folder/layer structure per domain.
- Define the middleware pipeline and its order.
- Define config + env validation approach.
- Record the foundation plan; implementation follows approved tasks only.
Decision Rules
- Structure by domain (e.g.
users/, orders/) with layers inside, once more than a couple of domains exist; a flat routes/ services/ split is fine for very small APIs.
- Async route errors must reach the central handler (wrapper or Express 5 behavior) — never
try/catch per route with ad-hoc responses.
- Keep Express thin: it routes and composes middleware; behavior lives in services.
Rules
- No scaffolding or dependency installation before task approval (Gate 4).
- Every baseline library justified against a requirement.
- Middleware order is part of the plan — it is behavior, not decoration.
Anti-Patterns
- Business logic in route handlers or middleware.
- Error responses assembled per-route instead of centrally.
- Unbounded body parsers; missing 404/error handlers.
- Copying a boilerplate repo wholesale without evaluating its choices.
Validation Checklist
Definition of Done
A recorded Express foundation plan — layering, middleware order, config, error handling, justified baseline libraries — ready to drive approved implementation tasks.
Related Skills
backend-stack-selection, backend-api-architecture, backend-error-handling, backend-validation, backend-security, backend-observability, ../../architecture-design.
Related Knowledge
../../../knowledge/ (team conventions, runtime constraints).
Related References
../../../references/backend/express/ (structure examples, when populated).
Context Loading Guidance
- Requires: approved stack decision, domain list, architecture summary.
- Does not require: database internals, other packs, unrelated references.
- May load:
backend-api-architecture, backend-error-handling.
- Stop when: the foundation plan is recorded.
Token Efficiency Guidance
Plan from the domain list; describe structure as a short tree + rules, not generated files. Delegate details to the specialist skills.
1---2name: express-foundation3description: Use to plan an Express API foundation after Express is approved — layered structure (routes/controllers/services/data), middleware order, config, error handler, baseline security middleware. Plans only; scaffolds nothing without task approval.4---56# Express Foundation78## Purpose910Define the foundation of an approved Express API: folder layering, middleware pipeline, configuration, central error handling, and baseline libraries — so the "unopinionated" framework still yields a disciplined codebase.1112## When to Use1314- After `backend-stack-selection` chose Express and Gate 2 approved it.15- **Not** for NestJS (`nestjs-foundation`) or before the stack decision.1617## Inputs1819- Approved stack decision and architecture (`../../architecture-design`).20- Domain list and expected API surface.2122## Discovery Questions2324- TypeScript (usually yes) — and which runtime/tooling does the team use?25- Which cross-cutting middleware is needed (auth, rate limiting, logging, CORS)?26- What config/environments exist (`../../environment-audit` conventions)?2728## Responsibilities2930- Define layering: **routes → controllers/handlers → services (business logic) → data layer** — logic never lives in route handlers.31- Define middleware order: request ID/logging → security headers → CORS → body parsing (with limits) → auth → validation → route → central error handler last.32- Plan config loading with validated env vars (fail fast on missing).33- Plan the central error handler (`backend-error-handling`) and 404 handling.34- Select baseline libraries by need (validation, logging, security headers) — each justified, none auto-installed.3536## Required Workflow37381. Confirm approval + architecture inputs.392. Define the folder/layer structure per domain.403. Define the middleware pipeline and its order.414. Define config + env validation approach.425. Record the foundation plan; implementation follows approved tasks only.4344## Decision Rules4546- Structure by **domain** (e.g. `users/`, `orders/`) with layers inside, once more than a couple of domains exist; a flat `routes/ services/` split is fine for very small APIs.47- Async route errors must reach the central handler (wrapper or Express 5 behavior) — never `try/catch` per route with ad-hoc responses.48- Keep Express thin: it routes and composes middleware; behavior lives in services.4950## Rules5152- No scaffolding or dependency installation before task approval (Gate 4).53- Every baseline library justified against a requirement.54- Middleware order is part of the plan — it is behavior, not decoration.5556## Anti-Patterns5758- Business logic in route handlers or middleware.59- Error responses assembled per-route instead of centrally.60- Unbounded body parsers; missing 404/error handlers.61- Copying a boilerplate repo wholesale without evaluating its choices.6263## Validation Checklist6465- [ ] Layering defined; logic placed in services.66- [ ] Middleware pipeline ordered and justified.67- [ ] Config/env validation planned (fail fast).68- [ ] Central error handler + 404 planned.69- [ ] Baseline libraries each justified; nothing installed yet.7071## Definition of Done7273A recorded Express foundation plan — layering, middleware order, config, error handling, justified baseline libraries — ready to drive approved implementation tasks.7475## Related Skills7677`backend-stack-selection`, `backend-api-architecture`, `backend-error-handling`, `backend-validation`, `backend-security`, `backend-observability`, `../../architecture-design`.7879## Related Knowledge8081`../../../knowledge/` (team conventions, runtime constraints).8283## Related References8485`../../../references/backend/express/` (structure examples, when populated).8687## Context Loading Guidance8889- **Requires:** approved stack decision, domain list, architecture summary.90- **Does not require:** database internals, other packs, unrelated references.91- **May load:** `backend-api-architecture`, `backend-error-handling`.92- **Stop when:** the foundation plan is recorded.9394## Token Efficiency Guidance9596Plan from the domain list; describe structure as a short tree + rules, not generated files. Delegate details to the specialist skills.
ahtishamshahzad