# BAT-010 Design

## Layering design

- `jarca_ledger_mcp/application/shared.py`
  - 공통 helper, validation, clock, dedupe, parser imports, shared policy를 보유한다.
- `jarca_ledger_mcp/application/system_services.py`
  - health/status/backup/account create-list 등 system/persistence-adjacent service를 담당한다.
- `jarca_ledger_mcp/application/asset_account_services.py`
  - account update, manual asset, snapshot, liquidity/net-worth read/write helper를 담당한다.
- `jarca_ledger_mcp/application/transaction_report_services.py`
  - transaction CRUD, budgets, monthly/category/fixed-cost/reporting helper를 담당한다.
- `jarca_ledger_mcp/application/import_transfer_services.py`
  - import preview/import, self-transfer/cancel reconciliation, cross-transfer matching을 담당한다.
- `jarca_ledger_mcp/application/categorization_services.py`
  - category rules, preview/apply, uncategorized workbench, ledger categories를 담당한다.

## Persistence design

- `jarca_ledger_mcp/infrastructure/sqlite/connection.py`
  - DB path resolution, sqlite connect, `db()` context manager를 담당한다.
- `jarca_ledger_mcp/infrastructure/sqlite/schema.py`
  - schema version, DDL, additive column maps를 보유한다.
- `jarca_ledger_mcp/infrastructure/sqlite/migrations.py`
  - idempotent/additive migration과 `init_db()`를 담당한다.
- top-level `jarca_ledger_mcp/db.py`는 compatibility shim으로 유지한다.

## Adapter / gateway design

- `jarca_ledger_mcp/adapters/mcp/server.py`
  - 실제 FastMCP registration 위치.
- top-level `jarca_ledger_mcp/server.py`
  - CLI entrypoint shim.
- `jarca_ledger_mcp/adapters/streamlit/service_gateway.py`
  - dashboard가 실제로 사용하는 service surface만 재노출한다.
- `dashboard/app.py`
  - gateway import를 통해 backend core를 호출한다.

## Compatibility design

- top-level `service.py`는 public API를 그대로 재노출한다.
- monkeypatch 관성을 위해 `service._current_kst_datetime` 변경이 shared/application modules에 전파되도록 module proxy를 유지한다.
- 기존 tests/import callers는 `from jarca_ledger_mcp import service` / `from jarca_ledger_mcp.db import init_db` 경로를 그대로 쓴다.

## Verification design

- `python -m py_compile`로 새 package tree syntax check.
- `pytest -q`로 full regression 및 AppTest 포함 회귀 검증.
- `hermes mcp test jarca-ledger`로 MCP tool discovery/registration 확인.
- Browser smoke로 synthetic fixture DB 기반 `요약`, `자산/마감` 렌더 및 console JS error 유무 확인.