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