express — Developer Handoff

Entry point. Read this first. Everything else is referenced from here.

Generated: 2026-05-26 00:29:05 UTC · Repo root: /tmp/express · Remote: https://github.com/expressjs/express.git

1. What is this?

express — project manifest detected from package.json.

Detected stack: (none)

Repository signals:

• Prisma models: 0 (0 enums, 0 relations)
• NestJS controllers: 0 (0 endpoints)
• Next.js routes: 0 app/ + 0 pages/
• Frontend components: 0

Full stack + topology: see ARCHITECTURE · INFRASTRUCTURE

2. Current state

• Branch: master
• HEAD: dae209ae6559
• Remote: https://github.com/expressjs/express.git

Recent commits:

• dae209a build(deps): bump github/codeql-action from 4.35.1 to 4.35.2 (#7212) — dependabot[bot] (2026-05-17)

3. Top 10 risks (bus-factor warning)

Generated by Luxscope static analysis (static + churn + ownership).

Band totals: 0 HIGH · 3 MED · 53 LOW (56 files scanned)

Full risk dashboard: risks/RISKS.md · risks/SUMMARY.txt. Interactive site: web/index.html. Per-file explain files: explain/.

4. How to get started

1. Read README — install, dev scripts, ports.
2. Read ARCHITECTURE — topology, request flows.
3. Read BEST_PRACTICES — git workflow + commit conventions.
4. Read DEPLOYMENT before touching staging/prod.
5. Read RUNBOOK on first incident.

5. Aux artefacts

• diagrams/module-graph.html
• diagrams/call-graph.html
• diagrams/classes.html
• diagrams/er-diagram.html (Prisma-based)
• risks/risks.json, risks/risks.sarif

Code ownership

No CODEOWNERS file detected. Add .github/CODEOWNERS so reviewers are auto-requested and new contributors know who maintains what.

express — Local Developer Setup

Generated by Luxscope handoff. Re-run luxscope handoff to refresh.

Prerequisites

• Node.js >= 18
• Package manager: npm

Setup

1. git clone https://github.com/expressjs/express.git
2. cd express
3. npm install

Run dev

(none detected)

Detected service ports (from docker-compose.yml):

(none detected via docker-compose; check framework defaults: Next.js 3000, NestJS 3000, Express varies)

Test

Unit:

• npm run test — mocha --require test/support/env --reporter spec --check-leaks test/ test/acceptance/

Quality gates

• npm run lint — eslint .
• npm run lint:fix — eslint . --fix

Environment

• See .env.example (if present at repo root) for required variables.
• See DEPLOYMENT.md for staging/production env handling.

What next

• New to the codebase? Read HANDOFF.md and HOWTO.md.
• Architecture overview: ARCHITECTURE.md.
• Contribution rules: BEST_PRACTICES.md.

express — How To

Stack-specific playbook. Read README.md first for setup; this file is the day-1 / week-1 task playbook.

Day 1

• Read HANDOFF.md (entry point) and ARCHITECTURE.md (topology).

• Run dev locally per README.md.

• Hit a health endpoint (look in API_REFERENCE_DETAIL.md for /health, /healthz, /ping).

• Run the full test suite once to confirm a clean baseline:

  npm test
  

• Skim risks/RISKS.md — top 10 files are the bus-factor + complexity hot spots.

Week 1 — Common operations

Ship a change

1. Branch from main (or develop if the repo uses GitFlow).
2. Make the change. Keep the PR ≤ 400 LOC where possible.
3. Run quality gates locally — see README.md.
4. Open a PR; follow conventions in BEST_PRACTICES.md.
5. Wait for CI green + 1 reviewer approval before merge.

Where to look when something breaks

• RUNBOOK.md — incident playbooks
• risks/HIGH.md — files most likely to be the source of bugs
• SECURITY.md — auth and data protection conventions

Work in progress / known unknowns

Source markers (2)

2 TODO

Open pull requests (30)

Fetched from GitHub via the gh CLI. Mid-flight changes — coordinate before stomping on these branches.

express — Architecture

Detected no containers, 1 persona, 0 external systems. The diagrams below are deterministic — they reflect manifests, framework scanners, and infrastructure files. Run luxscope docs build --level hub --with-ai to add narrative prose without overwriting the C4 blocks.

Context (C4 Level 1)

C4Context
  title System Context for express
  Person(user, "End user", "Application user")
  System(system, "express", "Application under documentation")
  Rel(user, system, "Uses", "HTTPS")
  UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="2")

Containers (C4 Level 2)

C4Container
  title Container View for express
  Person(user, "End user")
  System_Boundary(boundary_express, "express") {
  }

express — API Reference

No NestJS controllers detected via AST scan. If this project uses a different HTTP framework or an OpenAPI spec, add openapi.json at the repo root and re-run luxscope handoff.

express — Database Schema

No prisma/schema.prisma detected. If this project uses a different ORM (TypeORM, Drizzle, Sequelize), the ER diagram is not yet supported.

express — Frontend

No Next.js app/ or pages/ routes detected.

express — Best Practices

No CLAUDE.md / AGENTS.md / .cursorrules detected. This document is a deterministic skeleton; run luxscope handoff --ai (premium) to fill guidance from CONTRIBUTING + CI config.

Testing

• (not detected in scan)

Linting

• Tools: eslint
• Scripts: lint, lint:fix

CI

• .github/workflows/ci.yml
• .github/workflows/codeql.yml
• .github/workflows/legacy.yml
• .github/workflows/scorecard.yml

Release

• (not detected in scan)

Conventions to confirm

• Branch + commit conventions
• PR flow and review gates
• Testing expectations
• Release / deploy process

express — Deployment

Branch: master · HEAD: dae209ae6559

CI workflows detected

• .github/workflows/ci.yml
• .github/workflows/codeql.yml
• .github/workflows/legacy.yml
• .github/workflows/scorecard.yml

Infrastructure detected

• Dockerfiles: 0
• docker-compose files: 0
• Terraform dirs: 0
• Kubernetes manifests: 0

Narrative deployment procedure deferred to luxscope handoff --ai (premium).

express — Runbook

No runbooks detected at docs/runbooks/ or runbooks/. The skeleton below is a deterministic placeholder; run luxscope handoff --ai (premium) to synthesize an incident playbook from git history.

Observability

Recent fix commits (auto-detected)

No fix/hotfix/revert commits detected in recent history.

Common incidents

Each entry: Symptom → Diagnosis → Fix.

• Deployment failure: check CI workflow logs in .github/workflows/. Last deployable commit: see fix commits above.
• Database migration failure: check for pending migrations. Roll back to previous release tag.
• Service unavailability: verify health endpoints and container/process status.
• Add repo-specific incidents as they occur.

Rollback procedures

• Identify the last stable git tag: git tag --sort=-creatordate | head -5
• Create a revert PR or cherry-pick the breaking commit.
• If DB migration ran: restore from pre-migration backup before reverting code.
• Document repo-specific rollback procedures here.

express — Infrastructure

CI Workflows

• .github/workflows/ci.yml
• .github/workflows/codeql.yml
• .github/workflows/legacy.yml
• .github/workflows/scorecard.yml

Stack version pins

Authoritative versions for the moving pieces. When upgrading, treat this table as the contract: bump it with the change, not after.

express — Security

No docs/SECURITY.md detected. This document is a deterministic skeleton; run luxscope handoff --ai (premium) to synthesize policy prose.

Detected auth libraries

• (no auth libraries auto-detected)

Session / token model

• express-session
• cookie-session

Roles / authorization

• (not detected in scan)

Encryption at rest

• (not detected in scan)

Audit logging

• (not detected in scan)

Open gaps (verify manually)

• Rate limiting (express-rate-limit / @nestjs/throttler)
• Content Security Policy headers
• CSRF protection
• Audit log retention policy
• Secrets rotation procedure

Sections still requiring manual or AI authoring

• Authentication flow (sequence diagram per identity source)
• Authorization model (roles, tenant scoping, RLS)
• Data protection (at rest, in transit, encrypted columns, DLQ encryption)
• CSP / WAF / rate limiting policies
• Audit logging retention
• Known open security issues
• SOC 2 / compliance posture

express — Environment Variables

Detected 2 distinct environment variables. No .env.example / .env.sample / .env.template found at repo root — the table below is grep-only and Required is best-effort.

express — Migration History

No migrations directory detected. Luxscope looked in: prisma/migrations, apps/api/prisma/migrations, packages/db/prisma/migrations, db/migrations, migrations, supabase/migrations.

express — Test Strategy & Coverage Map

Deterministic snapshot of test infrastructure: which runners are configured, where specs live, what coverage CI enforces, and what's currently shipping.

Latest coverage report

No coverage/coverage-summary.json found. Run the coverage script (often test:cov, test --coverage, or vitest run --coverage) to generate one before relying on these numbers.

Test scripts

Detected test entry points across workspaces.

Layer guidance

• Unit — pure functions, mock external dependencies, no network. Fast.
• Integration — boots the framework, hits a real database or in-memory equivalent. Catches wiring bugs unit tests miss.
• E2E — spawns the full stack, drives the public surface (HTTP, browser). Slowest; reserve for journey coverage.

Default to the highest-speed layer that can still fail when the bug returns.

express — Local Debugging Recipes

No log directories, health endpoints, dev scripts, or stack-detected recipes found.

Document the local debugging entry points by hand in HOWTO.md if they live outside the standard paths.

express — First Commit Guide

Everything a new contributor needs to land their first PR without burning a half-day on convention discovery.

1. Preflight checklist

• No CONTRIBUTING.md detected — ask in the team channel before sending a PR.
• Pull main (or the project's default branch) and create your branch from it.

2. Branch naming

No branch policy detected. Conventional choice: feat/short-slug for features, fix/short-slug for fixes.

3. Commit format

No commitlint config detected. Default to Conventional Commits (feat: / fix: / chore: / docs:).

4. Hooks that run automatically

No .husky/ hooks detected. CI is the only line of defense — pull recent main before pushing.

5. Low-risk first-PR ideas

Detected directly from the repo. Each one is small enough to ship in a single PR:

• TODO at test/express.static.js:71 — @txt')
• TODO at test/express.static.js:721 — @txt')

6. Final checklist before pushing

• Tests pass for the area you touched.
• TypeScript / build is clean for the affected workspace.
• Commit message matches the format above.
• Branch name matches the policy above.
• Push, then open a PR against the default branch.

express — Onboarding Checklist

Concrete deliverables for a new engineer joining this repo. Every item points at a real file, command, or signal already detected in this bundle — no aspirational filler.

Day 1 — Boot the system

Goal: clone the repo, get the local stack up, hit one endpoint successfully, and read enough docs to know where things live.

• Clone the repo and read README.md + HOWTO.md end-to-end.
• Install Node >= 18 (engine pinned in package.json).
• Run npm install (or the equivalent for your package manager).
• Confirm services are listening on their expected ports.
• Pair with someone for 30 minutes — let them walk you through their last PR.

Week 1 — Build a mental model

Goal: read enough code to know what's load-bearing, what's risky, and how the team works.

• Read the top-risk files end-to-end (these are where the team gets paged):
  • test/res.redirect.js — band MED (4 findings)
  • test/res.location.js — band MED (11 findings)
  • lib/response.js — band MED (32 findings)
  • examples/view-locals/index.js — band LOW (20 findings)
  • examples/route-middleware/index.js — band LOW (16 findings)
• Run the full test suite at least once: npm test (so you know what "green" looks like locally).
• Ship a low-risk first PR — see FIRST_COMMIT.md for surfaced TODOs and skipped tests.

Month 1 — Own a slice

Goal: be the go-to person for at least one area of the system.

• Be primary reviewer on at least 5 PRs in your domain area.
• Lead a 30-minute walkthrough of one area for the next new hire.

Sign-off

Work down the boxes in order. When the Month-1 list is fully checked, you're no longer onboarding — you're a maintainer.

express — Glossary

No domain terms extracted. Add Prisma models, NestJS controllers, or hand-written runbooks to populate this section.

express — API Recipes

No NestJS endpoints or Next.js routes detected.

If the API uses a different framework (FastAPI, Express, Rails, ...), document the recipes by hand in HOWTO.md.

express — ADR Index

No ADRs detected. Luxscope looked under docs/adr/, docs/decisions/, and any *.adr.md files.

Even one ADR is better than none — start with a 5-line decision record the next time the team makes a non-obvious call.

express — Performance & Internationalization

No performance instrumentation or i18n machinery detected.

If perf metrics or translations live elsewhere (separate ops repo, vendor UI), document the location here by hand.

express — ER Diagram

No Prisma schema detected. Diagram unavailable.