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-5 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`

## 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.

Remaining:
1. Phase 6: `income`, `budget`, `payday` endpoints.
2. Phase 7: `dashboard` + `crisis-status`.
3. Phase 8: `admin` + site access endpoints.
4. 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.