CapaKraken/docs/architecture-hardening-backlog.md

Architecture Hardening Backlog

Date: 2026-03-30 Purpose: Keep the remaining cleanup work for the current quality/security scope in a single prioritized list, so small hardening slices can be completed before larger redesign work.

Recently Completed

• SSE audience model narrowed to canonical user:*, permission:*, and resource:* scopes only
• CI architecture guardrail added for SSE audience scoping
• import boundaries hardened for server dispo workbooks and browser spreadsheet uploads
• AI and SMTP runtime diagnostics sanitized before they reach logs or admin-facing error messages
• transitive audit hotspots for flatted and picomatch pinned through root pnpm.overrides
• apps/web export paths migrated from direct xlsx usage to a shared exceljs workbook export helper
• packages/application workbook reading and packages/engine XLSX export serialization migrated from xlsx to exceljs
• pnpm audit --audit-level=high no longer reports high-severity dependency findings
• apps/web now has focused Vitest coverage for browser spreadsheet parsing and skill-matrix workbook parsing
• cron routes, Redis helpers, reminder scheduling, webhook dispatching, and SSE fallback paths now use structured logger calls instead of raw console.*
• packages/api now has focused Vitest coverage for reminder scheduler and webhook dispatcher logging failures
• apps/web typecheck is now decoupled from generated .next-e2e artifacts via a dedicated tsconfig.typecheck.json
• comment entity support is now centralized across shared constants, API registry policy, assistant tool metadata, and the web comment target API without pretending a second consumer exists
• resource is now onboarded as the second real comment entity, reusing the same ownership and staff-visibility rules as the resource detail route
• comment mention autocomplete now uses a dedicated entity-scoped API route instead of inheriting the narrower user.listAssignable audience
• runtime secret handling is now environment-first end to end: admin updates no longer persist new operational secrets, runtime status is surfaced explicitly, and legacy database secret copies can be cleared through a dedicated cleanup path
• apps/web system settings UI is now decomposed into section components with shared secret/runtime helpers, bringing all files in that slice back under the file-size guardrail

Next Up

Pin the next structural cleanup on the API side: split packages/api/src/router/assistant-tools.ts into domain-oriented tool modules without changing the public tool contract.

Remaining Major Themes

The small hardening slices are effectively exhausted. The remaining work is now structural rather than another quick batch:

1. secrets and runtime configuration policy
2. oversized router decomposition
3. production-grade rate limiting
4. canonical image-based production delivery
5. performance hotspot reduction

Working Rule

For the next batches, prefer work in this order:

1. remove or isolate known-risk runtime dependencies
2. add guardrails and tests around already-hardened code
3. only then expand architecture surface area