added udner construction for file compaction, planning for unbloating

docs/api-refactor-lightweight-plan.md

@@ -0,0 +1,67 @@
+# API Refactor Lightweight Plan
+
+## Goal
+Reduce `api/src/server.ts` size and duplication with low-risk, incremental moves.
+
+Current state (2026-03-15):
+- `server.ts` has ~4.8k lines and 50 endpoint registrations.
+- Duplicate endpoint signatures also exist in `api/src/routes/*` but are not currently registered.
+
+## Refactor Guardrails
+1. Keep route behavior identical while moving code.
+2. Move one domain at a time; do not mix domains in one PR.
+3. Do not redesign architecture (no repositories/DI/container work).
+4. Extract only duplicated logic into shared helpers/services.
+5. Preserve global hooks and plugin registration in `server.ts` until final cleanup.
+6. Keep response shapes stable (`ok`, `code`, `message`, etc.) during moves.
+7. Require tests to pass after each move phase.
+
+## Canonical Source Rule
+`server.ts` is the canonical route logic right now.
+
+When moving a domain:
+1. Copy current logic from `server.ts` into the domain route module.
+2. Register the module.
+3. Remove the original block from `server.ts`.
+4. Confirm no duplicate route registrations remain.
+
+## Shared Helpers (Phase 0)
+Create these helpers first to keep endpoint moves lightweight:
+
+1. `api/src/services/user-context.ts`
+- `getUserTimezone(...)`
+- Removes repeated user timezone lookup logic.
+
+2. `api/src/services/category-shares.ts`
+- `computePercentShares(...)`
+- `computeWithdrawShares(...)`
+- `computeOverdraftShares(...)`
+- `computeDepositShares(...)`
+- Centralizes repeated category-share math.
+
+3. `api/src/services/budget-session.ts`
+- `getLatestBudgetSession(...)`
+- `ensureBudgetSession(...)`
+- `ensureBudgetSessionAvailableSynced(...)`
+- Prevents session/value drift bugs.
+
+4. `api/src/services/api-errors.ts`
+- Standard typed error object and response body builder.
+- Keeps endpoint error handling consistent.
+
+## Move Order (Incremental)
+1. Low-risk endpoints: `health`, `session`, `me`, `user/config`.
+2. `auth` + `account` endpoints.
+3. `variable-categories` endpoints.
+4. `transactions` endpoints.
+5. `fixed-plans` endpoints.
+6. `income`, `budget`, `payday` endpoints.
+7. `dashboard` + `crisis-status`.
+8. `admin` endpoints.
+
+## Definition of Done per Phase
+1. Endpoints compile and register once.
+2. Existing tests pass.
+3. No route path/method changes.
+4. No response contract changes.
+5. `server.ts` net line count decreases.