jarca-ledger-mcp/docs/batches/bat-011_20260703_transactional-write-service-split/design.md

BAT-011 Design

Architecture summary

• Introduce dedicated write-oriented application modules under jarca_ledger_mcp/application/ for accounts, transactions, budgets, and category rules/categories.
• Keep broad modules (system_services.py, asset_account_services.py, transaction_report_services.py, categorization_services.py) as compatibility aggregation layers for read/report/mixed responsibilities that are not yet in scope.
• Preserve service.py as a thin re-export facade and avoid MCP/Streamlit/dashboard call-site churn.

Changed areas

• jarca_ledger_mcp/application/accounts_write_services.py
• jarca_ledger_mcp/application/transactions_write_services.py
• jarca_ledger_mcp/application/budgets_write_services.py
• jarca_ledger_mcp/application/category_rules_write_services.py
• Existing application modules that previously held these implementations
• jarca_ledger_mcp/application/__init__.py
• jarca_ledger_mcp/service.py

Key decisions

• Move only mutation implementations in BAT-011; read/report/import/advanced workflow logic stays in place.
• Favor direct function relocation plus compatibility re-export over new abstraction layers to minimize contract risk.
• Keep shared helpers in application/shared.py; do not introduce storage-layer refactors in this batch.

Edge cases

• create_ledger_account remains paired with update_ledger_account even though the old implementations lived in different modules.
• Category rule preview/apply remains out of BAT-011 scope if moving it would force read/workbench coupling; mutation extraction takes precedence.
• Any dashboard/MCP references must continue resolving through service.py without signature changes.

Architecture Impact

• none

Reference Doc Update Plan

• No baseline doc rewrite in BAT-011 unless the final module tree differs materially from the existing dcy-011/REQ-015 description.