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-30
• Source Discovery / Batch: bootstrap-baseline, BAT-006
• 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.
• .github/workflows/ci.yml :: GitHub Actions CI gate runner for PR/push/manual checks.

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: Dashboard operations hub overview

1. Operator opens the 요약 page.
2. Dashboard resolves the KST current month and calls get_monthly_cashflow_report(month) using transactions.transaction_date and ledger_categories.cashflow_kind semantics.
3. Dashboard calls get_asset_liquidity_report, which groups active accounts by accounts.liquidity_bucket and uses only accounts.last_balance for asset/liability values.
4. Dashboard renders sections in REQ-005 priority order: this-month actual income/expense/net/savings rate, asset liquidity, asset composition, budget/spend, operational warnings.
5. Missing last_balance account rows are excluded from asset totals and surfaced as warnings; transaction sums are not used to estimate non-transaction assets.

Flow: CI validation gates

1. GitHub Actions starts .github/workflows/ci.yml on pull_request, push to main, or workflow_dispatch.
2. pytest-regression installs the project with dev/dashboard extras and runs pytest --ignore=tests/test_dashboard_app.py so service/parser/regression failures fail the workflow.
3. dashboard-app-test runs pytest tests/test_dashboard_app.py; the AppTest test creates a synthetic fixture DB through scripts/ci_fixture_db.py, sets JARCA_LEDGER_DB_PATH, and asserts core dashboard pages render without Streamlit exceptions.
4. dashboard-http-smoke runs scripts/ci_dashboard_http_smoke.py; the wrapper creates a temp fixture DB, starts Streamlit on loopback, polls for HTTP 200, then terminates the process.
5. db-safety-smoke runs scripts/ci_db_safety_smoke.py; the wrapper creates temp source/backup/target DB files and invokes scripts/ledger_restore_smoke.py without touching the operating DB path.
6. Any job failure fails the workflow. Stable job names are intended for branch protection configuration outside the repository.
7. CI logs are status-oriented and synthetic-data-only; they must not contain real account identifiers, raw payloads, statement filenames, balances from the operating DB, or passwords.

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: Operational backup, validation DB, and restore smoke

1. Operator captures non-sensitive DB status evidence with get_ledger_db_status: path, size, mtime, sha256, integrity check, major table row counts, and aggregate totals.
2. Operator creates a timestamped backup in /root/.local/share/jarca/backups/ledger/ with create_ledger_backup; retention keeps the most recent 30 days or newest 20 files.
3. Risky import, rollback, categorization apply, reconciliation, or migration work is tested first against a synthetic fixture DB or repo-external validation DB copy selected through JARCA_LEDGER_DB_PATH.
4. Backup list/status/hash checks use list_ledger_backups and get_ledger_backup_status.
5. Restore execution is not an MCP flow. Restore smoke uses scripts/ledger_restore_smoke.py or the runbook and requires explicit approval before overwriting an existing target DB.
6. Verification evidence must not include full transaction dumps, full merchant/counterparty dumps, account identifiers, raw_payload, original financial file contents, or passwords.

Flow: Statement-unavailable manual balance reconciliation

1. Operator follows the dcy-002 safety standard first: capture DB status, create or confirm a recent backup, and run preview/reconcile on a validation DB before operating on the production DB.
2. Operator marks accounts with statement_status: manual_only for statement-unavailable accounts, partial_import for accounts that require manual supplementation, or import_supported where normal statement import is sufficient.
3. Operator records manual evidence transactions with source='manual', positive amount, date, account, and non-sensitive memo/source context.
4. Operator runs get_balance_reconciliation_report from MCP/service or the dashboard account page. If baseline_at is YYYY-MM, the snapshot time is that month end at 23:59 KST; ad-hoc reconciliation uses the user-supplied snapshot timestamp.
5. The report compares baseline_balance/last_balance with the latest balance_after if available, otherwise with net signed account transactions. Absolute tolerance is 1,000 KRW; 0.1% of baseline is reference-only.
6. OK rows need no immediate triage. REVIEW_NEEDED rows present manual decision candidates: 계좌이동, 실지출, 실수입, 투자이동, 분석제외, 확인필요.
7. This flow does not run automatic scheduling, notifications, restore, or auto-confirming mutation.

Flow: Streamlit browser evidence capture

1. Operator runs scripts/streamlit_browser_evidence.py from the repository root.
2. The script creates a synthetic fixture DB under the evidence output directory and refuses to use the default operating DB path.
3. Streamlit starts with JARCA_LEDGER_DB_PATH=<fixture.sqlite3> on a local loopback port.
4. /usr/bin/google-chrome-stable runs in headless mode through Chrome DevTools Protocol and opens target dashboard pages such as 분류 규칙, 확인필요 큐, and Import.
5. After page title text is rendered, the script stores PNG screenshots, DOM snapshots, and manifest.json in the evidence directory.
6. UI/dashboard-impacting batches must attach browser screenshot/snapshot evidence. Non-UI batches may treat it as optional, and docs-only batches do not require browser evidence.
7. If Chrome/browser capture is unavailable, AppTest + HTTP 200 fallback evidence is allowed only as PASS_WITH_NOTES with the environment failure and remaining browser-evidence item recorded.
8. Browser screenshot/DOM evidence is not a required GitHub Actions gate in BAT-006. Run it locally for visual/layout-sensitive dashboard changes, while non-visual backend/CI changes can rely on pytest/AppTest/HTTP/DB safety gates.

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.
• Before broad DB mutation, capture DB status evidence and create or confirm a recent backup.
• Restore execution is script/runbook only and must not be exposed as an MCP tool.
• Manual balance reconciliation must remain preview/report-first unless a future REQ approves persistent review routing and confirmation mutation.
• Streamlit browser evidence must use synthetic/validation DBs only and must not screenshot/log real account numbers, balances, source financial filenames, passwords, full merchant/counterparty dumps, or raw payloads.
• CI gates must use synthetic/temp DBs only. The default operating DB path (~/.local/share/jarca/ledger.sqlite3) is forbidden for AppTest, HTTP smoke, and DB safety smoke wrappers.
• Dashboard asset liquidity calculations must use accounts.liquidity_bucket and accounts.last_balance; loan is excluded from the asset composition denominator and reflected as debt/net-worth only.
• Sensitive passwords are runtime inputs and must not be committed.

Current Gaps / Planned Changes

• Browser-level evidence is available locally through scripts/streamlit_browser_evidence.py; it remains outside required CI gates by design.
• Dedicated reconciliation workbench and persistent review-decision queue are deferred beyond REQ-003.
• Separate asset snapshot/manual asset tables and automatic market/real-estate valuation are deferred beyond REQ-005.

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.
• 2026-06-27 10:17 KST: BAT-002/REQ-002 기준으로 운영 backup/status/list/hash 및 restore 제한 flow 추가.
• 2026-06-29 KST: REQ-003/BAT-003 기준으로 statement-unavailable 수동 잔액대조 flow 추가.
• 2026-06-29 KST: REQ-004/BAT-004 기준으로 Streamlit browser evidence capture flow 및 UI evidence gate 기준 추가.
• 2026-06-29 KST: REQ-005/BAT-005 기준으로 dashboard operations hub 및 liquidity_bucket/last_balance 자산 유동성 flow 추가.
• 2026-06-30 KST: REQ-006/BAT-006 기준으로 GitHub Actions CI validation gates, synthetic fixture DB boundary, AppTest/HTTP/DB safety smoke flow, local browser evidence boundary 추가.