124 lines
5.1 KiB
Markdown
124 lines
5.1 KiB
Markdown
# 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-26 22:24
|
|
- Source Discovery / Batch: bootstrap-baseline
|
|
|
|
## 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
|
|
|
|
## 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
|
|
|
|
```text
|
|
jarca-ledger-mcp/
|
|
├── README.md
|
|
├── pyproject.toml
|
|
├── uv.lock
|
|
├── .env.example
|
|
├── 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/
|
|
│ ├── 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
|
|
├── docs/
|
|
│ ├── discovery/
|
|
│ ├── srs/
|
|
│ ├── batches/
|
|
│ ├── 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, 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 summaries, transaction filtering, uncategorized triage, rule management, review queues, categories, accounts, and import operations.
|
|
- `tests/`
|
|
- Regression tests for service behavior, parser behavior, categorization, category rules, cross-account transfer matching, and ledger category semantics.
|
|
|
|
## 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.
|
|
- 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.
|
|
|
|
## Current Gaps / Planned Changes
|
|
- Final UX verification is still needed for 분류 규칙 삭제, 취소/환급 원거래 연결, and import E2E flows.
|
|
- CI workflow and deployment/service management are not yet defined.
|
|
- Long-term policy for accounts without downloadable statements remains partially operational/documentation work.
|
|
|
|
## 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.
|