# benjamin-awd/monopoly architecture

> Architecture diagram of the GitHub repository benjamin-awd/monopoly, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benjamin-awd/monopoly
- Repository: https://github.com/benjamin-awd/monopoly

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    CLI["CLI (`monopoly/cli.py`)"]:::cli
    click CLI "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/cli.py"

    %% Configuration & Environment
    subgraph "Configuration & Environment"
        EnvTemplate[".env.template"]:::infra
        click EnvTemplate "https://github.com/benjamin-awd/monopoly/blob/main/.env.template"
        Config["Config Loader (`config.py`)"]:::config
        click Config "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/config.py"
        Constants["Constants Directory"]:::config
        click Constants "https://github.com/benjamin-awd/monopoly/tree/main/src/monopoly/constants/"
        Enums["Enums (`enums.py`)"]:::config
        click Enums "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/enums.py"
    end

    %% External Dependencies
    subgraph "External Binaries" 
        Poppler["Poppler (`pdftotext`)"]:::external
        OCR["OCRmyPDF"]:::external
    end

    %% Core Pipeline
    Pipeline["Pipeline (`pipeline.py`)"]:::core
    click Pipeline "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/pipeline.py"
    Handler["Coordinator (`handler.py`)"]:::core
    click Handler "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/handler.py"

    %% PDF Ingestion & Text Extraction
    subgraph "PDF Ingestion & Text Extraction"
        PDFIngestor["PDF Ingestor (`pdf.py`)"]:::core
        click PDFIngestor "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/pdf.py"
        TextPages["Text Pages"]:::data
    end

    %% Bank Detection & Parser Factory
    subgraph "Bank Detection & Parsers"
        Detector["Detector (`detector.py`)"]:::parser
        click Detector "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/detector.py"
        BaseParser["Base Parser Interface (`base.py`)"]:::parser
        click BaseParser "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/base.py"
        subgraph "Bank Parsers"
            BOA["Bank of America (`boa.py`)"]:::parser
            click BOA "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/bank_of_america/boa.py"
            Chase["Chase (`chase.py`)"]:::parser
            click Chase "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/chase/chase.py"
            Citibank["Citibank (`citibank.py`)"]:::parser
            click Citibank "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/citibank/citibank.py"
            DBS["DBS (`dbs.py`)"]:::parser
            click DBS "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/dbs/dbs.py"
            HSBC["HSBC (`hsbc.py`)"]:::parser
            click HSBC "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/hsbc/hsbc.py"
            Maybank["Maybank (`maybank.py`)"]:::parser
            click Maybank "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/maybank/maybank.py"
            OCBC["OCBC (`ocbc.py`)"]:::parser
            click OCBC "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/ocbc/ocbc.py"
            SC["Standard Chartered (`standard_chartered.py`)"]:::parser
            click SC "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/standard_chartered/standard_chartered.py"
            Trust["Trust (`trust.py`)"]:::parser
            click Trust "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/trust/trust.py"
            UOB["UOB (`uob.py`)"]:::parser
            click UOB "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/uob/uob.py"
            ZKB["ZKB (`zkb.py`)"]:::parser
            click ZKB "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/zkb/zkb.py"
            ExampleBank["Example Bank (`example_bank.py`)"]:::parser
            click ExampleBank "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/banks/example_bank.py"
        end
    end

    %% Generic Parser
    subgraph "Generic Parser"
        GenericHandler["Generic Handler (`handler.py`)"]:::parser
        click GenericHandler "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/generic/handler.py"
        GenericCore["Generic Core (`generic.py`)"]:::parser
        click GenericCore "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/generic/generic.py"
        Patterns["Patterns (`patterns.py`)"]:::parser
        click Patterns "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/generic/patterns.py"
    end

    %% Domain Models
    subgraph "Domain Models"
        BaseStmt["Base Statement (`base.py`)"]:::model
        click BaseStmt "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/statements/base.py"
        CreditStmt["Credit Statement (`credit_statement.py`)"]:::model
        click CreditStmt "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/statements/credit_statement.py"
        DebitStmt["Debit Statement (`debit_statement.py`)"]:::model
        click DebitStmt "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/statements/debit_statement.py"
        Transaction["Transaction Model (`transaction.py`)"]:::model
        click Transaction "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/statements/transaction.py"
    end

    %% CSV Writer
    CSVWriter["CSV Writer (`write.py`)"]:::core
    click CSVWriter "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/write.py"

    %% Utilities & Logging
    subgraph "Logging & Utilities"
        Logging["Logging (`log.py`)"]:::util
        click Logging "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/log.py"
        Identifiers["Identifiers (`identifiers.py`)"]:::util
        click Identifiers "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/identifiers.py"
        DateConst["Date Constants"]:::util
        click DateConst "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/constants/date.py"
        StmtConst["Statement Constants"]:::util
        click StmtConst "https://github.com/benjamin-awd/monopoly/blob/main/src/monopoly/constants/statement.py"
    end

    %% Filesystem / Output
    FS["Filesystem / STDOUT"]:::infra

    %% Connections
    CLI -->|"load args"| Config
    CLI -->|"start pipeline"| Pipeline
    Config -->|"provide env"| PDFIngestor
    PDFIngestor -->|"PDF → Text"| TextPages
    TextPages -->|"detect bank"| Detector
    Detector -->|"select parser"| BaseParser
    BaseParser --> BankParsers
    Detector -->|"no match"| GenericHandler
    GenericHandler --> GenericCore
    GenericCore --> Patterns
    BankParsers -->|"parse text"| Transaction
    GenericHandler -->|"parse text"| Transaction
    Transaction -->|"build statement"| BaseStmt
    BaseStmt --> CreditStmt
    BaseStmt --> DebitStmt
    BaseStmt -->|"validate totals"| CSVWriter
    CSVWriter --> FS
    Logging --> CLI
    Identifiers --> PDFIngestor
    DateConst --> BaseParser
    StmtConst --> BaseParser

    %% External Binaries Integration
    PDFIngestor --- Poppler
    PDFIngestor --- OCR

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px;
    classDef config fill:#bbf,stroke:#333,stroke-width:1px;
    classDef core fill:#bfb,stroke:#333,stroke-width:1px;
    classDef parser fill:#fbf,stroke:#333,stroke-width:1px;
    classDef model fill:#ffb,stroke:#333,stroke-width:1px;
    classDef util fill:#fcf,stroke:#333,stroke-width:1px;
    classDef infra fill:#ddd,stroke:#333,stroke-width:1px;
    classDef external fill:#fee,stroke:#333,stroke-width:1px;
```
