68 lines
2.3 KiB
Markdown
68 lines
2.3 KiB
Markdown
# 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.
|