jarca-ledger-mcp/docs/runtime-flows.md

Jarca Ledger MCP Runtime Flows

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

Project Summary

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

Purpose

• This document is the current execution-flow baseline for the project.
• It is a cross-cutting reference document for Discovery, REQ, Batch Design, Batch Verification, and implementation updates.

Scope

• Covers representative command, MCP, dashboard, import, and reconciliation flows.
• Does not duplicate full acceptance criteria or low-level implementation details.

Covered Entry Points

• jarca-ledger-mcp :: MCP stdio server for Hermes tool calls.
• dashboard/app.py :: Streamlit local dashboard.
• pytest :: regression test runner.

Shared Components

• SQLite database at ~/.local/share/jarca/ledger.sqlite3 by default.
• jarca_ledger_mcp.service as the central domain/service layer.
• Parser modules for KB/Toss/SeoulPay sources.
• Category and cashflow_kind semantics shared by reports and UI.

Flow: MCP server tool call

1. Hermes MCP client invokes a tool exposed by jarca_ledger_mcp.server.
2. server.py forwards arguments to the matching service.py function.
3. service.py opens the SQLite database path from env/default, validates inputs, and performs the operation.
4. Service returns a dictionary payload with success data or error information.
5. Hermes surfaces the tool result to the user or uses it in a follow-up workflow.

Flow: Streamlit dashboard operation

1. Operator starts streamlit run dashboard/app.py --server.address 0.0.0.0 --server.port 8501.
2. Dashboard reads the configured/default SQLite database.
3. User navigates to 요약, 거래내역, 확인필요 큐, 미분류, 분류 규칙, 카테고리, 계좌, or Import pages.
4. UI calls service functions for reads, updates, imports, categorization, and manual linking.
5. UI displays success/error status and refreshes visible tables.

Flow: Import preview and import

1. Operator chooses or supplies a supported source file: KB Bank PDF, Toss Bank PDF, Toss Securities PDF, SeoulPay XLSX, or CSV.
2. Preview function parses the file and reports counts, sample rows, duplicate status, and classification preview.
3. On explicit import, service creates/fetches the target account, inserts non-duplicate transactions, writes raw provenance, and records an import batch.
4. Reports and dashboard views read the inserted rows using category and cashflow semantics.
5. If an import is wrong, rollback uses import batch data and soft-deletes by default.

Flow: Categorization rule lifecycle

1. Operator creates or edits a category rule with match field, pattern, target category/subcategory, priority, and optional amount/day constraints.
2. Preview categorization shows candidate matches without mutating rows.
3. Apply categorization updates matching transactions and preserves audit information.
4. Category cashflow_kind controls actual cashflow/report inclusion.

Flow: Cross-account and cancel/original reconciliation

1. Preview functions search candidate pairs by amount, date, direction, account/source compatibility, and text similarity.
2. Operator reviews candidates in the dashboard or runs the automatic matcher where confidence rules are satisfied.
3. Matched self-transfers become 이체 / 본인계좌이동; investment movements become 이체 / 투자이동; ambiguous rows remain 확인필요.
4. Cancel/refund rows can be linked to original expense rows; memo tags preserve manual link evidence.

Flow Constraints

• Preview before broad import or categorization mutation where supported.
• Do not include transfer, investment, exclude, or unresolved rows in actual household spending totals unless a report explicitly asks for account movement.
• Preserve raw import evidence for audit and future reclassification.
• Avoid destructive migrations without a backup/approval plan.
• Sensitive passwords are runtime inputs and must not be committed.

Current Gaps / Planned Changes

• Need final browser-level UX verification for rule delete and cancel/original linking dialogs.
• Need CI/deployment flow if this project will be maintained beyond local operation.
• Need a documented operational process for statement-unavailable accounts.

Update Triggers

• Update this document when a command entry point changes.
• Update this document when a runtime orchestration path changes.
• Update this document when a batch changes the approved flow baseline.

Change Log

• 2026-06-26 22:24 KST: Created by bootstrap-baseline from repository observation.