🧹 Technical Debt & Maintainability

📋 Summary

Midshift carries a moderate, mostly well-understood level of technical debt. Roughly a third of the application's source files are touched by at least one measurable debt signal (high complexity, duplication, dead code, or an unmaintained library), but most of that is light: duplication overall is low (2.3%) and the typical function is simple. The debt that matters is concentrated in a few places: a critically out-of-date framework version, a handful of very large request handlers that mix many rules together, permission and write logic that is not applied in one consistent place, hand-run database changes, and a large test double that has to be kept in step with every server route. Unusually, the code contains no "TODO" or "FIXME" markers at all; the debt is instead recorded in prose in the project's own notes (CLAUDE.md), which is thorough but easy for a new team to miss. A new team could change this code with reasonable safety in the pure business-logic layer, which is well tested, and with considerably less safety in the server routes, which have almost no automated unit tests.

🎯 Rating

🟡 ●●●○○ 3 / 5 — Amber. Debt is moderate and largely documented, but the riskiest parts (authorisation, fat route handlers, manual migrations, vulnerable framework pin) sit exactly where test protection is thinnest.

🔍 Findings

1. Debt inventory

2. Marker count

grep -rn for TODO, FIXME, HACK, XXX, @deprecated across src, supabase, scripts, e2e: 0 occurrences of each. [Observed] This does not mean there is no debt; it means debt is tracked in CLAUDE.md and docs/HANDOVER.md ("The queue, in order", "Parked decisions") rather than in code. A new team should migrate those into an issue tracker. [Inferred]

3. Maintainability — how safely could a new team change this?

Verdict: a competent team could take this over, provided it first adds tests around authorisation and the high-CCN route handlers before refactoring them. [Inferred]

4. Debt quantification

Method. Of the 395 non-test TypeScript files under src/, count a file as materially affected if it has at least one of: a function with CCN > 20 (lizard), participation in a clone ≥ 70 tokens (jscpd), being acknowledged dead code, or being the consumer of an unmaintained dependency.

Estimate: about one third of source files are touched by measurable debt, but the severity-weighted share is much lower. Most duplication hits are small (2.3% of lines overall) and many sit in the QA harness mirroring production pages (e.g. workspace/campaign/[id]/layout.tsx ↔ qa/_lib/campaign-shell.tsx, 78 lines). The materially risky debt is concentrated in roughly 15–20 files: the six fat route handlers, for-you.ts, api-auth.ts, the browser components that write directly, and the QA store. [Inferred — judgement, method as above]

Worst duplicated pairs (jscpd, lines): workspace/campaign/[id]/layout.tsx ↔ qa/_lib/campaign-shell.tsx 78; media-strategy/route.ts ↔ wrapup/route.ts 46; review/files/route.ts ↔ upload/[token]/register/route.ts 46; workspace/campaigns/page.tsx ↔ qa/campaigns/page.tsx 44; plan/route.ts ↔ qa/store.ts 40. [Observed]

5. Prioritised remediation backlog

🧾 Evidence

• grep -rn "TODO|FIXME|HACK|XXX|@deprecated" → 0 each.
• node /tmp/…/debt.js over lizard.csv and jscpd-report.json → 43 complex files, 108 duplicated-block files, union 131 of 395 non-test files.
• find src -name "*.ts" -o -name "*.tsx" | grep -v .test. | wc -l → 395.
• ls "src/app/(app)/campaign/[id]/" → checklist/, build/ present; ls e2e/checklist.spec.ts present.
• supabase/baseline.sql lines 2 and 46–50; README.md lines 70–71; src/types/database.ts:3.
• Cross-references: Modules 2 (complexity), 3 (architecture), 4 (business rules), 5 (duplication), 7 (coverage), 8 (dependencies), 12 (documentation).

⚠️ Risks

✅ Recommendations