hledger-preprocessor

User Story DAG Explorer

Step 1a: Account Configuration

US-1a.1: Configure a single bank account with CSV import ▶
US-1a.2: Configure multiple bank accounts ▶
US-1a.3: Configure a cash wallet (no CSV) ▶
US-1a.4: Configure a cryptocurrency exchange account ▶
US-1a.5: Configure matching algorithm parameters ▶
US-1a.6: Configure base currency for reporting ▶
US-1a.7: Configure multi-row CSV merging for exchanges with split transactions ▶

Step 1b: Category Configuration

US-1b.1: Define hierarchical spending categories ▶
US-1b.2: Add a new category after initial setup
US-1b.3: Use categories for income as well as expenses ▶

Step 2a: Receipt Image Processing

US-2a.1: Rotate a receipt image
US-2a.2: Crop a receipt image
US-2a.3: Process a batch of receipt images

Step 2b: Receipt Labelling

US-2b.1: Label a simple same-currency card receipt ▶
US-2b.2: Label a cash receipt ▶
US-2b.3: Label a foreign-currency receipt ▶
US-2b.4: Label a split-payment receipt (card + cash) ▶
US-2b.5: Label a receipt with returned items ▶
US-2b.6: Use AI suggestions during manual labelling
US-2b.7: Edit an existing receipt label
US-2b.8: Fully automated AI receipt labelling
US-2b.9: Date-range error feedback during receipt labelling
US-2b.10: Inline matching CLI when no unique CSV match ▶

Step 3: Receipt-to-CSV Transaction Matching

US-3.1: Auto-match a simple same-currency receipt
US-3.2: Match a foreign-currency withdrawal receipt to a bank CSV in a different currency
US-3.3: Match when no candidates are found (widen date range)
US-3.4: Match when no candidates are found (widen amount range)
US-3.5: Match when DD-MM and MM-DD date formats are swapped
US-3.6: Disambiguate when multiple matches are found (2-14 candidates)
US-3.7: Reduce search scope when too many matches are found (15+)
US-3.8: Correct a receipt label during matching
US-3.9: Match a receipt for a direct asset purchase (e.g. gold)
US-3.10: Skip matching for cash-only receipts
US-3.11: Handle a receipt with withdrawal fees
US-3.12: Handle multiple transactions on the same account in one receipt
US-3.13: Handle a foreign-currency receipt with returned items
US-3.14: Prevent linking the same CSV transaction to two receipts
US-3.15: Verify transaction data is up to date

Step 4: Pipeline Execution

US-4.1: Run the full pipeline end-to-end
US-4.2: Run the pipeline with randomised/scrambled data for demos
US-4.3: Generate hledger rules files for a bank
US-4.4: Optional incremental pipeline runs
US-4.5: Include opening balances from a starting journal
US-4.6: Detect uncategorised transactions before interactive matching
US-4.7: Report unmatched transactions before interactive matching
US-4.8: Auto-check receipt matching after TUI labelling

Step 5: Visualisation

US-5.1: Generate a Sankey diagram of money flows
US-5.2: Generate a Treemap of spending by category
US-5.3: Launch an interactive Dash dashboard
US-5.4: Filter visualisations by time period
US-5.5: Generate monthly/quarterly/yearly reports
US-5.6: Calculate personal inflation rate
US-5.7: Show a correlation matrix of combined-account payments
US-5.8: Drill down from treemap to time-series chart
US-5.9: Sticky toolbar with keyboard shortcuts
US-5.10: Select period granularity (weekly / monthly / yearly)
US-5.11: Hierarchical legend with group toggle in drill-down

Transaction Classification

US-C.1: Classify transactions using rule-based logic
US-C.2: Classify transactions using a self-hosted AI
US-C.3: Train a classification model on my own categorised data
US-C.4: Classify receipt images by category using AI

Cross-cutting Concerns

US-X.1: Privacy: no data leaves my machine
US-X.2: Reproducible pipeline output
US-X.3: Multi-bank, multi-currency support
US-X.4: Unique transaction hashes prevent duplicates
US-X.5: GIF demos are auto-generated from integration tests
US-X.6: Enforce one receipt image per transaction

User Story DAG

Interactive explorer — use → to start cycling through stories.