Files
jarca-ledger-mcp/docs/batches/bat-008_20260630_asset-snapshots-manual-assets-read-mcp/design.md
T

1.9 KiB

BAT-008 Design

Schema and persistence design

  • Add manual_assets as a first-class table for non-transaction-derived assets/liabilities.
  • Add asset_snapshots as an append-only history table keyed by basis date plus evaluated item identity.
  • Migrations remain additive/idempotent; existing ledger/account flows must continue to operate when both tables are empty.

Authority-source and valuation design

  • Account-backed assets use accounts.last_balance as the live authority source.
  • Non-transaction assets/liabilities use manual_assets as the live authority source.
  • asset_snapshots is a historical record layer, not a competing primary input source.
  • Net worth formula remains: asset buckets (cash, investment, deposit, real_estate, other) minus loan; missing valuations are excluded, not inferred.

Read model design

  • Service layer should expose:
    • manual assets list/report helpers
    • basis-date asset snapshot read helpers
    • net-worth timeseries helpers
    • shared valuation/fallback helpers consumed by both MCP and dashboard
  • Snapshot read responses must expose basis date, bucket totals, liabilities, net worth, and inclusion/exclusion explanation fields.
  • Manual assets read responses must expose item name, value, basis date, liquidity_bucket, and memo/source metadata.

Dashboard alignment design

  • dashboard/app.py should consume the same valuation helpers as the MCP read tools.
  • If no manual assets/snapshots exist, dashboard behavior must safely fall back to REQ-005 account-based display.
  • Excluded/unvalued items should be explainable instead of silently counted.

Verification design

  • Add targeted regression tests for:
    • additive migration creation
    • manual asset persistence and retrieval
    • snapshot accumulation/read behavior
    • net-worth formula / exclusion policy
    • dashboard/MCP shared fallback behavior
  • Prefer synthetic SQLite fixtures and temp DBs only.