refactor(projects): declarative route table [7/8]

[nourshoreibah]

Stack 7/8. Base is #346, not main. Last of the six conversions. Most routes and the trickiest ordering in the repo. Pure reorganization; no behaviour change.

handler.ts drops from 769 lines to 4. Route table, byte-for-byte the order of the original if chain:

#	Method	Pattern	Controller
1	GET	/projects/dashboard	dashboard.getDashboard
2	GET	/projects/:id/members	members.getMembers
3	GET	/projects/assignable-staff	members.getAssignableStaff
4	GET	/projects	projects.listProjects
5	GET	/projects/:id/overview	dashboard.getOverview
6	GET	/projects/:id/donors	donors.getProjectDonors
7	GET	/projects/:id	projects.getProject
8	PUT	/projects/:id	projects.updateProject
9	DELETE	/projects/:id	projects.deleteProject
10	POST	/projects	projects.createProject
11	GET	/projects/:id/expenditures	expenditures.getProjectExpenditures

/projects/dashboard and /projects/assignable-staff are two-segment patterns with the same shape as /projects/:id, so both must precede every :id route or dispatch's first-match-wins would route GET /projects/dashboard into "load the project with id dashboard". That was previously guaranteed only by the physical order of if blocks 200 lines apart. Both are now pinned by tests.

What the patterns replace: endsWith('/members'), endsWith('/overview'), parts.length === 3 && parts[2] === 'donors', and rawPath.split('/').length === 2.

Layout

At 769 lines this one earns a service layer:

• controllers/projects.ts — list, get, create, update, delete.
• controllers/dashboard.ts — dashboard, overview.
• controllers/members.ts — members, assignable-staff.
• controllers/donors.ts, controllers/expenditures.ts — the project-scoped sub-resources.
• services/projects.ts — loadProjectAggregates, syncMemberships, findUnknownUserIds, isProjectActive, indexByProject, projectIdFrom, toIsoDate.
• auth.ts untouched — it already holds the domain authorization checks (canAccessProject, canEditProject, canCreateProject, canDeleteProject), and controllers keep calling it.
• Local json() deleted in favour of the shared one.
• tsconfig.json's include gains controllers/**/*.ts and services/**/*.ts.

Authorization gates confirmed

• Create — still gated by canCreateProject(user.userId), 403 Admin access required.
• Delete — still gated by canDeleteProject(user.userId), 403 Admin access required, and id-format validation still runs before the authorization check, which is what test/delete-authz.unit.test.ts pins with its "400 before any authorization work" case. All 5 cases in that suite pass.
• Every route re-authenticates through createAuthGuard(authenticateRequest) at AUTHENTICATED, reproducing the old global if (!authContext.isAuthenticated || !authContext.user) return 401 gate with the same message and the same 401/403 split.

Tests

97 passed, 0 failed across 7 suites. A live Postgres was reachable, so the DB-backed suites ran too:

Suite	Result
projects.unit.test.ts	12
project-page.unit.test.ts	18 (17 original + 1 new precedence test)
delete-authz.unit.test.ts	5
dashboard.unit.test.ts	12
example.test.ts	6
crud.test.ts	12
projects.e2e.test.ts	pass

tsc --noEmit clean. Jest prints a harmless open-handle warning from the raw pg.Pool the test files construct directly — pre-existing, unrelated.

New precedence regression test:

test('/projects/dashboard is not parsed as a project id', async () => {
  const res = await handler(event('/dashboard', 'GET'));
  expect(res.statusCode).toBe(200);
  expect(parse(res).summary).toBeDefined();
});

Deliberately left alone

GET /projects/dashboard still selects every expenditure row and buckets it by month in a JS loop — the anti-pattern apps/backend/lambdas/AGENTS.md calls out by name. Moved verbatim, not fixed. Now that it is one named function in controllers/dashboard.ts instead of 165 lines wedged in a routing chain, fixing it is a tractable follow-up PR. All SQL, transaction boundaries, validation order, status codes and message strings unchanged.

Noticed, not fixed

projects/openapi.yaml declares /health and /dashboard as top-level paths with no /projects prefix, while the actual runtime routes are /projects/health and /projects/dashboard — both before and after this change. Pre-existing; PR 8/8 normalizes the specs.

Stack-wide note: unmatched paths now 404 instead of 401

Previously the top-level auth check ran before route matching, so an unauthenticated request to a nonexistent path got 401. dispatch returns 404 centrally without running auth, so an unauthenticated caller can now distinguish "route exists" (401) from "route doesn't" (404). Accepted deliberately — the route inventory is already in the repo's openapi.yaml files, and auth-before-routing is exactly what forces each lambda to hand-roll public-route exemptions.

🤖 Generated with Claude Code