jarca-ledger-mcp/docs/data-model.md

Jarca Ledger MCP Data Model

• Baseline Mode: observed
• Baseline Seed: .stage-pilot/bootstrap/baseline.yaml
• Status: draft
• Owner: Jarca / project maintainer
• Last Updated (KST): 2026-06-29
• Source Discovery / Batch: bootstrap-baseline

Project Summary

• Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 현금흐름 분석을 SQLite에 저장하고 운영한다.

Purpose

• This document captures the current data-model baseline for future Discovery, REQ, Batch, and Release work.
• It focuses on durable entities, state rules, consistency rules, and persistence boundaries rather than implementation-only details.

Persistence Backend

• SQLite database at ~/.local/share/jarca/ledger.sqlite3 by default.
• Override path through JARCA_LEDGER_DB_PATH.
• Schema initialization and migrations are managed by jarca_ledger_mcp/db.py.

Entity: LedgerAccount

• Source of Truth: ledger_accounts
• Purpose: Represents bank, card, cash, investment, or loan accounts used to attach transaction evidence and balances.
• Lifecycle: created -> updated -> inactive/archived
• Key Fields:
  • id :: text :: stable account identifier
  • name :: text :: operator-facing account name
  • type :: text :: bank/card/cash/investment/loan classification
  • institution :: text :: financial institution or source
  • account_number_masked :: text :: masked account identifier
  • holder_name :: text :: owner context for transfer matching
  • last_balance :: integer :: latest known balance when available
  • last_synced_at :: text :: 기준 잔액 스냅샷 시각. 정기 대조는 월말 23:59 KST, 수시 대조는 사용자 입력 시각
  • statement_status :: text :: unknown, import_supported, manual_only, partial_import
  • liquidity_bucket :: text :: cash, investment, deposit, real_estate, loan, other; 자산 유동성/구성/순자산 집계의 계좌 단위 권위 소스
• Relationships:
  • transactions.account_id links rows to accounts.
• State Rules:
  • active=false hides accounts from default lists without deleting history.
  • manual_only is the statement-unavailable class; partial_import remains eligible for manual supplementation and balance reconciliation.
  • Balance reconciliation is report/preview first: compare baseline_balance/baseline_at against the latest balance_after or net account transaction delta, with 1,000 KRW absolute tolerance.
  • 비거래 자산/부채는 별도 평가 테이블 없이 last_balance를 현재 평가액/잔액, last_synced_at을 기준일, memo를 출처 메모로 사용한다.
  • liquidity_bucket='loan'은 자산 구성 비율 분모에서 제외하고 총부채/순자산 산식에만 반영한다. last_balance가 없는 계좌/자산은 임의 거래 합계로 추정하지 않는다.

Entity: Transaction

• Source of Truth: transactions
• Purpose: Represents imported or manually entered financial event evidence.
• Lifecycle: created/imported -> categorized/reconciled -> soft-deleted or retained
• Key Fields:
  • transaction_date :: date text :: ledger date
  • posted_date / transaction_datetime :: text :: source timing detail where available
  • type :: text :: income, expense, transfer, refund, or adjustment
  • amount :: integer :: positive KRW amount
  • category / subcategory :: text :: household classification
  • merchant, counterparty, description, payment_method :: text :: evidence and display fields
  • source, external_id, import_batch_id, raw_summary, raw_payload :: text :: provenance and audit fields
  • memo :: text :: operator notes and reconciliation tags
  • status :: text :: active/deleted/review lifecycle state where used
• Relationships:
  • belongs to LedgerAccount through account_id
  • linked to ImportBatch through import_batch_id
  • interpreted with LedgerCategory through category/subcategory
• State Rules:
  • Amount is stored positive; type determines direction.
  • Cancellation/refund rows should use refund type when confirmed.
  • Manual link evidence should be memo-tagged rather than silently rewritten.

Entity: LedgerCategory

• Source of Truth: ledger_categories
• Purpose: Defines category/subcategory labels and their cashflow semantics.
• Lifecycle: seeded/created -> updated -> inactive/deleted
• Key Fields:
  • category :: text
  • subcategory :: text
  • cashflow_kind :: text :: income, expense, transfer, investment, debt_payment, exclude, unknown
  • sort_order, memo, active
• Relationships:
  • Referenced by Transaction classification.
  • Targeted by CategoryRule results.
• State Rules:
  • cashflow_kind controls inclusion in actual household cashflow reports.
  • Transfer, investment, exclude, and unresolved kinds are not actual household spending unless a report explicitly asks for account movements.

Entity: CategoryRule

• Source of Truth: category_rules
• Purpose: Automatic classification policy for transactions.
• Lifecycle: created -> previewed/applied -> updated/deactivated/deleted
• Key Fields:
  • match_field :: text :: field to inspect
  • pattern :: text :: match pattern
  • match_type :: text :: contains/equals/regex
  • category / subcategory :: text :: classification target
  • priority :: integer :: deterministic ordering
  • amount_min, amount_max, day_of_month :: integer nullable :: optional constraints
  • person, is_fixed, confidence, memo, active
• Relationships:
  • Applies to Transaction rows.
  • Should target valid or intentional category/subcategory labels.
• State Rules:
  • Preview should precede broad application when changing classification behavior.
  • More specific/high-priority rules should avoid accidentally overriding unrelated evidence.

Entity: ImportBatch

• Source of Truth: import_batches
• Purpose: Tracks grouped imports for audit and rollback.
• Lifecycle: previewed -> imported -> optionally rolled back
• Key Fields:
  • id :: text :: import batch identifier
  • source :: text :: source kind
  • file_path / source metadata where stored
  • inserted_count, skipped_duplicate_count, created_at, rolled_back_at
• Relationships:
  • Transaction rows reference import_batch_id.
• State Rules:
  • Rollback should soft-delete by default.
  • Duplicate imports with skip_duplicates=True may insert zero rows; that is not automatically an error.

Entity: Budget

• Source of Truth: budget table/service functions
• Purpose: Monthly category/subcategory/person budget target.
• Lifecycle: created/updated -> compared against actual spending
• Key Fields:
  • month, category, subcategory, person, amount, currency, memo
• Relationships:
  • Compared against Transaction aggregates by report functions.

Entity: LedgerBackupArtifact

• Source of Truth: filesystem under /root/.local/share/jarca/backups/ledger/ by default
• Purpose: Timestamped SQLite backup artifact used for operational recovery and validation smoke checks.
• Lifecycle: created -> listed/status-checked -> retained/pruned by policy -> optionally restored by script/runbook after approval
• Key Evidence Fields:
  • path :: text :: backup file path outside repository
  • size_bytes :: integer :: file size metadata
  • mtime :: text :: filesystem modification time
  • sha256 :: text :: file checksum
  • integrity_check :: text :: SQLite integrity result
  • table_counts / aggregate_totals :: metadata-only validation evidence
• State Rules:
  • Keep backups from the most recent 30 days or newest 20 files.
  • Backup artifacts and validation DB copies must not be committed to git.
  • Restore execution is not a persisted MCP operation and requires script/runbook approval controls.

Consistency Rules

• Actual cashflow reports include only categories whose cashflow_kind represents actual income or expense according to report semantics.
• Account movement summaries should be separate from actual household income/expense summaries.
• Cross-account auto-matching requires same date, same amount, opposite direction, and compatible source/owner evidence.
• External counterparty securities transfers are review items unless matched or explicitly confirmed.
• Import evidence fields are retained for audit and future correction.
• DB corrections should be narrow and memo-tagged.
• Dashboard asset liquidity/net-worth reports use accounts.liquidity_bucket and accounts.last_balance only; transactions are not used to infer non-transaction asset values.

Persistence Notes

• Schema changes should be additive/idempotent unless a destructive migration is explicitly approved and backed up.
• Operational backup/status evidence may include only path, size, mtime, checksum, integrity, row counts, and aggregate totals.
• Validation DB copies should live outside the repository and should be selected explicitly via JARCA_LEDGER_DB_PATH when used.
• Passwords for encrypted imports are runtime-only inputs and are not part of the persisted model.
• Raw payloads may contain sensitive financial evidence and should not be committed to git.

Current Gaps / Planned Changes

• Formal schema migration documentation should be added before larger DB changes.
• Some UI workflows need final E2E verification against real rows.
• Statement-unavailable account handling is tracked by REQ-003/BAT-003; future work may add a dedicated reconciliation workbench and persistent review-decision queue.
• REQ-005/BAT-005 adds dashboard operations hub semantics and account-level liquidity buckets; future work may add separate asset snapshots only after a new REQ.

Change Log

• 2026-06-26 22:24 KST: Created by bootstrap-baseline from repository observation.
• 2026-06-27 10:17 KST: BAT-002/REQ-002 기준으로 LedgerBackupArtifact와 metadata-only evidence 정책 추가.
• 2026-06-29 KST: REQ-003/BAT-003 기준으로 accounts.statement_status와 수동 잔액대조 preview 모델 추가.
• 2026-06-29 KST: REQ-005/BAT-005 기준으로 accounts.liquidity_bucket, last_balance 기반 자산 유동성/부채/순자산 규칙 추가.