X-Financial/docs/superpowers/plans/2026-06-22-refactor-under-800-lines.md

# Refactor Under 800 Lines Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Keep every Python class and every frontend core component/module under 800 lines, while deleting proven dead code and reducing avoidable runtime overhead.

**Architecture:** Add automated code-size guardrails first, then split oversized units by existing responsibility boundaries. Preserve public APIs wherever possible, move private helpers into focused modules, and delete code only after usage checks or tests prove it is not needed.

**Tech Stack:** Vue single-file components, Vite/Node test runner, Python/FastAPI service layer, pytest inside Docker container `x-financial-main`.

---

### Task 1: Guardrails

**Files:**
- Create: `web/tests/code-size-limits.test.mjs`
- Create: `server/tests/test_code_size_limits.py`

- [x] **Step 1: Add frontend source-unit limit test**

```bash
node --test web/tests/code-size-limits.test.mjs
```

Expected current result: FAIL, listing oversized files in `web/src/components`, `web/src/composables`, `web/src/utils`, and `web/src/views`.

- [x] **Step 2: Add backend class limit test**

```bash
docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-main /tmp/x-financial-server-venv/bin/pytest -q server/tests/test_code_size_limits.py
```

Expected current result: FAIL, listing Python classes over 800 lines.


### Task 2: Backend Python Class Split

**Files:**
- Modify: `server/src/app/services/user_agent_application.py`
- Modify: `server/src/app/services/risk_rule_template_executor.py`
- Modify: `server/src/app/services/steward_planner.py`
- Modify: `server/src/app/services/receipt_folder.py`
- Modify: `server/src/app/services/expense_claim_draft_flow.py`
- Modify: `server/src/app/services/expense_claims.py`
- Modify: `server/src/app/services/orchestrator_execution.py`
- Modify: `server/src/app/services/finance_dashboard.py`
- Modify: `server/src/app/services/agent_assets.py`
- Create focused helper or mixin files under `server/src/app/services/`

- [ ] **Step 1: Split low-risk helper groups first**

Move private formatting, parsing, label, and serialization methods into helper mixins or helper modules. Keep original public classes and method names stable.

- [ ] **Step 2: Split domain-heavy groups**

Move larger responsibility groups into named mixins:

```text
UserAgentApplicationMixin
├── application fact resolution
├── application persistence
└── application duplicate/detail helpers

RiskRuleTemplateExecutor
├── condition evaluators
├── value resolvers
└── date/window parsing

ReceiptFolderService
├── storage/meta helpers
├── editable field resolution
└── train ticket extraction
```

- [ ] **Step 3: Verify backend class limit**

```bash
docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-main /tmp/x-financial-server-venv/bin/pytest -q server/tests/test_code_size_limits.py
```

Expected final result: PASS.

- [ ] **Step 4: Run targeted backend regression tests**

```bash
docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-main /tmp/x-financial-server-venv/bin/pytest -q server/tests/test_user_agent_service.py server/tests/test_expense_claim_service.py server/tests/test_steward_planner.py server/tests/test_risk_rule_generation.py server/tests/test_agent_asset_service.py server/tests/test_reimbursement_endpoints.py
```

Expected final result: PASS or a documented pre-existing failure with evidence.


### Task 3: Frontend Source Unit Split

**Files:**
- Modify: `web/src/components/business/PersonalWorkbenchAiMode.vue`
- Modify: `web/src/views/scripts/TravelReimbursementCreateView.js`
- Modify: `web/src/views/scripts/TravelRequestDetailView.js`
- Modify: `web/src/views/scripts/useTravelReimbursementSubmitComposer.js`
- Modify remaining files reported by `web/tests/code-size-limits.test.mjs`
- Create focused modules beside the existing owners under `web/src/views/scripts/`, `web/src/components/`, `web/src/composables/`, and `web/src/utils/`

- [ ] **Step 1: Split pure helpers before stateful runtime code**

Extract pure formatting, payload normalization, label mapping, row building, and text rendering helpers. This reduces file size without changing component state ownership.

- [ ] **Step 2: Split composables and child components**

For Vue files, move stable repeated UI blocks into child components only when props/events are clear. For script modules, move independent computed builders and action helpers into colocated modules.

- [ ] **Step 3: Remove proven redundant frontend code**

Use `rg` to confirm an export, class, helper, CSS hook, or branch is unused before deleting it. If a usage is dynamic, keep it unless a regression test proves it is dead.

- [ ] **Step 4: Verify frontend source limit**

```bash
node --test web/tests/code-size-limits.test.mjs
```

Expected final result: PASS.

- [ ] **Step 5: Run targeted frontend regression tests**

```bash
node --test web/tests/workbench-ai-mode-switch.test.mjs web/tests/expense-application-fast-preview.test.mjs web/tests/expense-profile-detail-modal.test.mjs web/tests/finance-dashboard-ranking.test.mjs
npm --prefix web run build
```

Expected final result: PASS.


### Task 4: Performance And Cleanup Pass

**Files:**
- Modify only files already touched by Tasks 2 and 3 unless a usage check proves a separate dead module can be removed.

- [ ] **Step 1: Remove repeated computation inside hot paths**

Cache local computed values inside functions, avoid repeated JSON/string/date parsing loops, and prefer early returns for blocked states.

- [ ] **Step 2: Delete redundant private helpers**

Delete helpers only when all of these checks are true:

```bash
rg "helperName" server web
node --test affected-web-test.mjs
docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-main /tmp/x-financial-server-venv/bin/pytest -q affected_server_test.py
```

- [ ] **Step 3: Final verification**

```bash
node --test web/tests/code-size-limits.test.mjs
docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-main /tmp/x-financial-server-venv/bin/pytest -q server/tests/test_code_size_limits.py
npm --prefix web run build
```

Expected final result: PASS.