jarca-ledger-mcp/.stage-pilot/bootstrap/baseline.yaml

schema_version: 1
capture_mode: observed

project:
  repository_name: jarca-ledger-mcp
  display_name: Jarca Ledger MCP
  summary: Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 현금흐름 분석을 SQLite에 저장하고 운영한다.
  primary_domain: Korean household finance ledger and transaction reconciliation

stack:
  tech_stack:
    - Python >=3.11
    - FastMCP / MCP server
    - SQLite
    - Streamlit dashboard
    - pandas / plotly dashboard dependencies
    - PyMuPDF PDF parsing
    - openpyxl + msoffcrypto-tool for encrypted Excel imports
    - pytest test suite

runtime:
  primary_runtime: mixed
  primary_entrypoints:
    - name: jarca-ledger-mcp
      purpose: MCP stdio server exposing ledger/account/category/import/report tools to Hermes Agent.
    - name: dashboard/app.py
      purpose: Streamlit dashboard for local ledger review, categorization, import, and manual reconciliation.
    - name: pytest
      purpose: Regression tests for service logic, import parsers, categorization rules, and transfer matching.

interfaces:
  contracts:
    - name: MCP tool surface
      type: internal-service
      actors: Hermes Agent and MCP clients
      purpose: Provide structured tools for ledger transactions, categories, budgets, imports, reports, and reconciliation.
      stability: internal
      inputs:
        - Python function/tool arguments validated by server.py signatures.
        - File paths and optional passwords for import preview/import tools.
      outputs:
        - Dictionary responses with success/error payloads; existing success shapes should remain backward compatible.
      errors:
        - validation_error for invalid parameters.
        - parser/import-specific errors for unreadable files, password issues, validation failures, or duplicate handling.
      compatibility_rules:
        - Preserve existing success response shapes for existing tools unless a planned migration states otherwise.
        - Additive optional fields are preferred over breaking argument changes.
    - name: Streamlit dashboard
      type: web-app
      actors: Local operator using browser UI
      purpose: Display actual cashflow, transaction lists, uncategorized triage, rule management, import batches, and review queues.
      stability: internal
      inputs:
        - Local SQLite database selected through JARCA_LEDGER_DB_PATH or default path.
        - Uploaded PDF/XLS/XLSX files for supported import paths.
      outputs:
        - Streamlit pages, tables, dialogs, categorization updates, import results, and reconciliation actions.
      errors:
        - UI-level error messages for unavailable service functions, parser failures, and validation problems.
      compatibility_rules:
        - User-facing category/cashflow semantics must remain stable; UI should surface cashflow_kind where classification matters.
  shared_constraints:
    - Financial import evidence must preserve raw provenance fields where available.
    - Actual income/expense must stay separate from account movement, investment movement, and excluded double-count candidates.
    - Destructive DB migrations are not allowed without explicit backup/approval flow.
  current_gaps:
    - Streamlit UX needs final verification for rule deletion, cancel/original linking, and import E2E flows.
    - No formal CI workflow is present yet.
    - Project was recently initialized as a git/GitHub repository; release and deployment policy is not yet documented.

structure:
  planned_top_level_areas:
    - path: jarca_ledger_mcp/
      responsibility: MCP server package, SQLite schema, service layer, import parsers, categorization, and reports.
    - path: dashboard/
      responsibility: Streamlit operator UI for ledger review and manual workflows.
    - path: tests/
      responsibility: pytest regression tests for parsers, service operations, categorization, and matching.
    - path: docs/
      responsibility: StagePilot baseline, Discovery, SRS, Batch, and Release documentation.
    - path: .stage-pilot/
      responsibility: StagePilot bootstrap seed and local process metadata.

data_model:
  persistence_backend: SQLite database at ~/.local/share/jarca/ledger.sqlite3 by default, overrideable through JARCA_LEDGER_DB_PATH.
  entities:
    - name: LedgerAccount
      purpose: Represents bank, card, cash, investment, or loan accounts used to attach transaction evidence and balances.
      source_of_truth: ledger_accounts table
      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
        - last_balance :: integer :: latest known balance when available
      relationships:
        - Transaction :: account_id links transaction rows to an account
      state_rules:
        - active=false hides accounts from default listings without deleting history.
    - name: Transaction
      purpose: Represents imported or manually entered financial event evidence with direction, amount, classification, provenance, and memo tags.
      source_of_truth: transactions table
      lifecycle: created/imported -> categorized/reconciled -> soft-deleted or retained
      key_fields:
        - transaction_date :: date text :: ledger date
        - type :: text :: income/expense/transfer/refund/adjustment direction
        - amount :: integer :: positive KRW amount
        - category/subcategory :: text :: household ledger classification
        - source/external_id/import_batch_id :: text :: import provenance and dedupe evidence
      relationships:
        - LedgerAccount :: account_id
        - LedgerCategory :: category/subcategory
        - ImportBatch :: import_batch_id
      state_rules:
        - amount is stored as a positive integer; type determines direction.
        - refund/cancel rows should be linked to the original transaction when confirmed.
    - name: LedgerCategory
      purpose: Defines category/subcategory semantics and cashflow_kind used by reports.
      source_of_truth: ledger_categories table
      lifecycle: seeded/created -> updated -> inactive/deleted
      key_fields:
        - category :: text :: top-level category
        - subcategory :: text :: optional subcategory
        - cashflow_kind :: text :: income/expense/transfer/investment/debt_payment/exclude/unknown
      relationships:
        - Transaction :: category/subcategory lookup
        - CategoryRule :: rule target category/subcategory
      state_rules:
        - cashflow_kind controls actual household cashflow inclusion semantics.
    - name: CategoryRule
      purpose: Defines automatic categorization rules with field, pattern, priority, and optional amount/day constraints.
      source_of_truth: category_rules table
      lifecycle: created -> previewed/applied -> updated/deactivated/deleted
      key_fields:
        - match_field :: text :: merchant/counterparty/raw_summary/etc.
        - pattern :: text :: contains/equals/regex match pattern
        - amount_min/amount_max/day_of_month :: integer :: optional match constraints
        - priority :: integer :: deterministic rule ordering
      relationships:
        - Transaction :: candidate rows updated by matching rules
      state_rules:
        - Preview before broad application when changing rules.
    - name: ImportBatch
      purpose: Tracks grouped imports for rollback and audit.
      source_of_truth: import_batches table
      lifecycle: previewed -> imported -> optionally rolled back
      key_fields:
        - id :: text :: batch identifier
        - source :: text :: import source kind
        - imported_count/skipped_duplicate_count :: integer :: result summary
      relationships:
        - Transaction :: import_batch_id
      state_rules:
        - Rollback should soft-delete by default unless explicitly hard-deleted.
  consistency_rules:
    - transfer/investment/exclude cashflow kinds are excluded from actual income/expense reports unless an account-movement report is requested.
    - Cross-account matches require same date, same amount, opposite direction, and compatible source labels before auto-confirmation.
    - Imported rows should retain raw_summary/raw_payload/counterparty/balance_after when available.
  persistence_notes:
    - Schema changes should be idempotent and additive by default.
    - Manual DB corrections should be narrow, ID-based, and memo-tagged for auditability.
  current_gaps:
    - Need formal migration/back-up procedure before destructive or structural migrations.
    - Need final UI verification for rule deletion and cancel/original linkage.

notes:
  known_unknowns:
    - Whether to add CI workflow and deployment/service management for the Streamlit dashboard.
    - Final UX acceptance criteria for mobile dashboard pages and rule deletion behavior.
    - Long-term handling policy for accounts where downloadable transaction statements are unavailable.

metadata:
  captured_at_kst: 2026-06-26 22:24
  source: bootstrap-baseline-repo-observation
  updated_from: repo-observation