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