jarca-ledger-mcp/docs/project-structure.md

Jarca Ledger MCP Project Structure

• 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, BAT-007

Project Summary

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

Primary Domain

• Korean household finance ledger and transaction reconciliation

Tech Stack

• Python >=3.11
• FastMCP / MCP server
• SQLite
• Streamlit dashboard
• pandas / plotly dashboard dependencies
• PyMuPDF, openpyxl, msoffcrypto-tool
• pytest
• ruff

Primary Runtime

• Type: mixed
• Planned Entry Points:
  • jarca-ledger-mcp :: MCP stdio server for Hermes Agent tools.
  • dashboard/app.py :: Streamlit dashboard for local ledger operations.
  • pytest :: Regression test entry point.

Purpose

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

Scope

• Covers top-level repository layout and package/module boundaries.
• Does not duplicate detailed business rules, acceptance criteria, or implementation-only function signatures.

Top-Level Structure

jarca-ledger-mcp/
├── README.md
├── pyproject.toml
├── uv.lock
├── .env.example
├── .github/
│   └── workflows/
│       └── ci.yml
├── dashboard/
│   └── app.py
├── jarca_ledger_mcp/
│   ├── __init__.py
│   ├── db.py
│   ├── service.py
│   ├── server.py
│   ├── kb_bank_pdf.py
│   ├── toss_bank_pdf.py
│   ├── toss_securities_pdf.py
│   └── seoulpay_xlsx.py
├── tests/
│   ├── contract_snapshots/
│   │   └── response_contract_v1_0.json
│   ├── test_contract_regression.py
│   ├── test_service.py
│   ├── test_categorization.py
│   ├── test_category_rule_filters.py
│   ├── test_cross_account_transfer_matching.py
│   ├── test_kb_bank_pdf.py
│   ├── test_toss_securities_pdf.py
│   ├── test_seoulpay_xlsx.py
│   └── test_ledger_categories.py
├── scripts/
│   ├── ci_fixture_db.py
│   ├── ci_dashboard_http_smoke.py
│   ├── ci_db_safety_smoke.py
│   ├── ledger_restore_smoke.py
│   └── streamlit_browser_evidence.py
├── docs/
│   ├── discovery/
│   ├── srs/
│   ├── batches/
│   ├── runbooks/
│   ├── releases/
│   ├── project-structure.md
│   ├── runtime-flows.md
│   ├── interface-contract.md
│   └── data-model.md
└── .stage-pilot/
    └── bootstrap/baseline.yaml

Package / Module Responsibilities

• jarca_ledger_mcp/db.py
  • SQLite connection, schema initialization, migrations, row conversion, and database path resolution.
• jarca_ledger_mcp/service.py
  • Domain service layer for accounts, transactions, categories, category rules, imports, reports, asset liquidity/net-worth aggregation, transfer matching, and manual link operations.
• jarca_ledger_mcp/server.py
  • FastMCP tool registration layer that exposes service functions to Hermes/MCP clients.
• jarca_ledger_mcp/kb_bank_pdf.py
  • KB 국민은행 encrypted PDF transaction parsing.
• jarca_ledger_mcp/toss_bank_pdf.py
  • Toss Bank transaction-history PDF parsing.
• jarca_ledger_mcp/toss_securities_pdf.py
  • Toss Securities transaction-history PDF parsing and transaction preview conversion.
• jarca_ledger_mcp/seoulpay_xlsx.py
  • SeoulPay encrypted XLSX parsing and preview conversion.
• dashboard/app.py
  • Streamlit operator UI for the operations hub summary, transaction filtering, uncategorized triage, rule management, review queues, categories, accounts/liquidity bucket editing, and import operations.
• tests/
  • Regression tests for service behavior, parser behavior, categorization, category rules, cross-account transfer matching, ledger category semantics, MCP response contract compatibility, and Streamlit AppTest dashboard smoke.
• tests/contract_snapshots/
  • Representative MCP response contract metadata/schemas. Version 1.0 is used by tests/test_contract_regression.py and intentionally asserts required subset/types so optional additive fields remain compatible.
• .github/workflows/ci.yml
  • GitHub Actions workflow for pull_request, push to main, and workflow_dispatch; stable required gate jobs are pytest-regression, dashboard-app-test, dashboard-http-smoke, db-safety-smoke, contract-regression, and lint.
• scripts/ci_fixture_db.py
  • Synthetic fixture DB builder for CI/AppTest/smoke checks. Refuses the default operating DB path and seeds only synthetic ledger data.
• scripts/ci_dashboard_http_smoke.py
  • CI HTTP smoke wrapper that creates a synthetic fixture DB, starts Streamlit on loopback, polls HTTP 200 readiness, and cleans up the process with status-only JSON output.
• scripts/ci_db_safety_smoke.py
  • CI DB safety wrapper that runs restore smoke through temp synthetic source/backup/target DB paths only and emits status-only JSON.
• scripts/streamlit_browser_evidence.py
  • Local browser evidence helper that creates a synthetic fixture DB, starts Streamlit with that DB, and captures Chrome screenshot/DOM snapshot artifacts for QC.
• scripts/ledger_restore_smoke.py
  • Script-only restore smoke helper for validation DBs; restore remains outside the MCP tool surface.

Dependency Rules

• server.py should remain a thin tool adapter and delegate business logic to service.py.
• Parser modules should parse source documents into structured records and avoid direct UI responsibilities.
• dashboard/app.py may call service functions but should not duplicate core classification/report semantics.
• DB schema migrations should be additive and idempotent by default.

Shared Boundaries

• cashflow_kind is the boundary between actual household income/expense and account movement/exclusion semantics.
• liquidity_bucket is the account-level boundary for asset liquidity/composition/debt/net-worth views; dashboard/app.py displays it and service.py computes it from accounts.last_balance.
• Import evidence fields (source, external_id, raw_summary, raw_payload, counterparty, import_batch_id) are audit boundaries and should be preserved.
• Manual reconciliation is represented through memo tags and narrow transaction updates, not broad rewrites.
• Browser evidence artifacts are generated from synthetic/validation DBs and should not embed real financial identifiers or raw source payloads.
• CI gate fixtures are generated at runtime under temp space by scripts/ci_fixture_db.py; CI and AppTest must not read the default operating DB path.
• MCP contract regression fixtures use pytest tmp_path synthetic DBs and committed schema metadata only; they must not read the operating DB or expose runtime contract_version fields.
• Branch protection required-check contract is documented in docs/interface-contract.md and represented by stable workflow job names. Applying branch protection remains an external GitHub repository setting.

Current Gaps / Planned Changes

• Local browser evidence capture exists for core Streamlit pages; browser screenshot/visual regression remains local evidence rather than a required CI gate.
• CI workflow now covers pytest/AppTest/HTTP smoke/DB safety smoke plus BAT-007 contract-regression/lint required-check jobs; branch protection enforcement remains a repository setting outside this codebase.
• Long-term policy for accounts without downloadable statements remains partially operational/documentation work.
• Separate automatic asset snapshots/manual asset tables are not present; BAT-005 uses account rows as the manual asset/liability source.

Update Triggers

• Update this document when package boundaries change.
• Update this document when new top-level runtime or domain modules are added.
• Update this document when a batch changes the approved structure baseline.

Change Log

• 2026-06-26 22:24 KST: Created by bootstrap-baseline from repository observation.
• 2026-06-29 KST: REQ-004/BAT-004 기준으로 scripts/streamlit_browser_evidence.py 및 browser evidence artifact 구조 추가.
• 2026-06-29 KST: REQ-005/BAT-005 기준으로 dashboard operations hub와 service asset liquidity aggregation 책임 추가.
• 2026-06-30 KST: REQ-006/BAT-006 기준으로 GitHub Actions CI workflow, synthetic fixture DB builder, AppTest/HTTP/DB safety smoke wrappers, CI-vs-local-browser evidence 경계 추가.
• 2026-06-30 KST: REQ-007/REQ-008/BAT-007 기준으로 MCP response contract snapshot/test 위치와 contract-regression/lint required-check job 계약 추가.