SkyMoney/docs/api-refactor-lightweight-plan.md

API Refactor Lightweight Plan

Goal

Reduce api/src/server.ts size and duplication with low-risk, incremental moves.

Current state (2026-03-17):

• server.ts still holds most business routes, but Phases 1-8 are complete.
• Completed move logs:
  • docs/api-phase1-move-log.md
  • docs/api-phase2-move-log.md
  • docs/api-phase3-move-log.md
  • docs/api-phase4-move-log.md
  • docs/api-phase5-move-log.md
  • docs/api-phase6-move-log.md
  • docs/api-phase7-move-log.md
  • docs/api-phase8-move-log.md

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 and/or finish these helpers 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.

Progress Snapshot

Completed:

1. Phase 1: low-risk endpoints (health, session, me, user/config).
2. Phase 2: auth + account endpoints.
3. Phase 3: variable-categories endpoints.
4. Phase 4: transactions endpoints.
5. Phase 5: fixed-plans endpoints.
6. Phase 6: income, budget, payday endpoints.
7. Phase 7: dashboard + crisis-status.
8. Phase 8: admin + site access endpoints.

Remaining:

1. Phase 9: final cleanup and helper consolidation.

Remaining Plan (Detailed)

Phase 5: Fixed Plans Domain

Move these routes out of server.ts into api/src/routes/fixed-plans.ts (or split module if needed):

1. PATCH /fixed-plans/:id/early-funding
2. POST /fixed-plans/:id/attempt-final-funding
3. PATCH /fixed-plans/:id/mark-unpaid
4. POST /fixed-plans/:id/fund-from-available
5. POST /fixed-plans/:id/catch-up-funding
6. POST /fixed-plans
7. PATCH /fixed-plans/:id
8. DELETE /fixed-plans/:id
9. POST /fixed-plans/:id/true-up-actual
10. GET /fixed-plans/due
11. POST /fixed-plans/:id/pay-now

Primary risk:

• Payment/funding workflows are tightly coupled with available budget math and rollover rules.

Test focus:

• api/tests/fixed-plans*.test.ts
• api/tests/payment-rollover.test.ts

Phase 6: Income, Budget, Payday Domain

Move these routes into a dedicated module (e.g., api/src/routes/budget-income.ts):

1. POST /income
2. GET /income/history
3. POST /income/preview
4. POST /budget/allocate
5. POST /budget/fund
6. POST /budget/reconcile
7. GET /payday/status
8. POST /payday/dismiss

Primary risk:

• Budget-session synchronization and allocator side effects.

Test focus:

• Income/budget allocation tests
• Any tests asserting payday status/dismiss behavior

Phase 7: Dashboard Read Domain

Move read endpoints into api/src/routes/dashboard.ts:

1. GET /dashboard
2. GET /crisis-status

Primary risk:

• Derived numbers diverging between dashboard and rebalance/session APIs.

Test focus:

• Dashboard API contract checks and UI smoke verification.

Phase 8: Admin and Site Access Domain

Move operational endpoints into api/src/routes/admin.ts and/or api/src/routes/site-access.ts:

1. POST /admin/rollover
2. GET /site-access/status
3. POST /site-access/unlock
4. POST /site-access/lock

Primary risk:

• Lockout/maintenance flow regressions and accidental open access.

Test focus:

• Site access flow tests
• Admin rollover auth/permission checks

Phase 9: Final Cleanup

1. Remove dead helper duplicates from server.ts and route modules.
2. Consolidate common helpers into api/src/services/*.
3. Normalize error envelopes where safe (no contract change unless explicitly planned).
4. Re-run full API/security suites and perform deployment smoke checks.

Reference Audit Requirement (Per Move)

For every endpoint moved:

1. Record original location in server.ts.
2. Record new route module location.
3. Record frontend references (web/src/api/*, hooks, pages).
4. Record test references.
5. Add a phase move log under docs/api-phaseX-move-log.md.

Verification Steps (Per Phase)

1. Build:

• cd api && npm run build

2. Run focused tests for moved domain.
3. Run security suites relevant to moved endpoints.
4. Deploy.
5. Run production endpoint smoke checks for the moved routes.
6. Confirm logs show expected status codes (no unexplained 401/403/500 shifts).

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.