How benjamin-awd/monopoly works
Main Components
a. CLI Layer
• monopoly/cli.py (entrypoint for the monopoly command)
b. Configuration & Environment
• .env / .env.template (PDF passwords)
• config.py, constants/, enums.py
c. PDF Ingestion & Text Extraction
• pdf.py (wrapper around Poppler’s pdftotext and optional OCRmyPDF)
• External dependencies: Poppler, OCRmyPDF
d. Bank Detection & Parser Factory
• banks/detector.py (auto-detect bank based on PDF properties)
• banks/base.py + per-bank modules (banks/bank_of_america/boa.py, banks/chase/chase.py, etc.)
e. Generic Parser
• generic/handler.py & generic/generic.py (fallback parsing patterns)
f. Processing Pipeline
• pipeline.py (orchestrates ingestion → detection → parsing → transformation)
• handler.py (ties together bank-specific or generic handlers)
g. Domain Models
• statements/*.py (Statement base, credit/debit, transaction.py)
h. CSV Writer
• write.py (transforms Statement objects into CSV rows)
i. Logging & Utilities
• log.py, identifiers.py, utils/ (date and pattern helpers)
Relationships & Data Flow
1. CLI → reads user arguments (file path(s), options)
2. Configuration → loads .env (passwords) and global constants
3. Pipeline
– Invokes PDF Ingestion → returns text pages
– Passes text to Bank Detector
• If match, instantiates bank-specific Parser
• Else falls back to Generic Parser
– Parser outputs a Statement object
– Statement is validated (safety check on totals)
– Statement passed to CSV Writer → writes output file(s)
4. Errors & logs propagate back to CLI for user feedback
[CLI] → [Config Loader]
[CLI] → [Pipeline] → [PDF Ingestor] → [Text Pages]
[Text Pages] → [Detector] ──> [Bank Parser X]
└──> [Generic Parser]
[Parser] → [Statement Model] → [CSV Writer] → [Filesystem / STDOUT]
Architectural Patterns & Principles
• Plugin / Factory Pattern for bank modules under src/monopoly/banks. Each bank implements the same interface (BaseBankParser).
• Pipeline / Orchestrator Pattern in pipeline.py: sequential stages (ingest, detect, parse, write).
• Separation of Concerns: PDF handling, detection, parsing, transformation, and I/O are decoupled.
• SOLID Principles: open for extension (new banks), closed for modification (core pipeline remains unchanged).
Technologies & Libraries
• Python 3.x (packaged via Poetry, pyproject.toml)
• pdftotext (Poppler) for PDF→text
• ocrmypdf (optional) for image-based statements
• CLI uses argparse/click in cli.py
• .env via python-dotenv or built-in env reader in config.py
Final Checklist
[ ] All major components (CLI, Config, Ingestor, Detector, Parsers, Pipeline, Writer)
[ ] External services and binaries (Poppler, OCRmyPDF)
[ ] Notes on extension points (adding new bank parser modules)