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

• Step 1: Add frontend source-unit limit test

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.

• Step 2: Add backend class limit test

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:

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

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

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

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

Expected final result: PASS.

• Step 5: Run targeted frontend regression tests

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:

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

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.