# eprbell/rp2 architecture

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

- Interactive diagram: https://gitdiagram.com/eprbell/rp2
- Repository: https://github.com/eprbell/rp2

## Overview

##### Main Components

- Command-line Interface (CLI) & Executables:
– The user-facing entry point (e.g., “rp2_us”, “rp2_jp”, etc.) that accepts arguments and invokes the core libraries.

- Input Processing:
– Input file reader and ODS parser module (src/rp2/ods_parser.py)
– Configuration loader (modules such as src/rp2/configuration.py and src/rp2/configuration_schema.py) that processes INI config files.

- Core Processing/Tax Engine:
– The accounting engine modules (src/rp2/accounting_engine.py)
– Core logic classes for transactions (e.g., src/rp2/in_transaction.py, src/rp2/intra_transaction.py, src/rp2/out_transaction.py)
– Modules that handle complex computations: balance, gain_loss, computed_data, tax_engine, and transaction_set.

- Plugin Architecture:
– Plugins for accounting methods (located under src/rp2/plugin/accounting_method/)
– Country-specific logic plugins (src/rp2/plugin/country/..)
– Reporting plugins that generate output files (src/rp2/plugin/report/ and supporting data files in src/rp2/plugin/report/data/)
– This design allows new output generators, countries, or accounting methods to be added modularly.

- Localization & Internationalization:
– The locales folder (under src/rp2/locales/) supports multiple languages and regions, using localized message catalogs.

- Logging and Error Handling:
– A logging module (src/rp2/logger.py) capturing runtime messages, errors, and debugging information.

- Testing and Quality Assurance:
– The tests folder contains various unit tests and integration tests (e.g., tests/test_tax_engine.py) ensuring correct computation.

##### Relationships and Interactions between Components

- The CLI component passes input parameters (files, accounting method, etc.) to the main module (src/rp2/rp2_main.py), which becomes the orchestrator.
- The main module:
– Loads configuration via the configuration modules.
– Reads and parses the ODS input file using the ods_parser.
– Delegates transaction parsing and processing to the accounting engine, which in turn uses various classes to build transaction sets and compute tax events (gain/loss, cost basis, etc.).
- The processing flow leverages the plugin system:
– Depending on the country and user accounting method (passed as command-line options), it dynamically loads the appropriate accounting method and country plugin.
– After calculations, it hands off data to the report generator plugin to produce detailed output reports.
- Logging is interwoven across these components to track the computation and provide audit trails.
- The testing suite is designed to validate each of these core components independently.

##### Important Architectural Patterns and Design Principles

- Modular Plugin Architecture:
– Enables extensibility: new accounting methods, country rules, or output formats can be added without disrupting core functionality.
- Separation of Concerns:
– The system distinctly separates input parsing, computation/processing, output generation, and logging.
- Configuration-driven Behavior:
– The use of external configuration files (INI files) allows the system’s behavior to be tailored without code changes.
- High Precision Arithmetic:
– Given the importance of computing correct tax figures, the core math modules (e.g., rp2_decimal.py) handle precision carefully.

##### Relevant Technologies and Frameworks

- Python 3.8+ as the primary programming language.
- Standard Python tooling (setuptools via setup.py, pytest/unittest for testing, and Mypy for type checking).
- ODS parsing which is likely facilitated by external libraries or custom code (with stubs provided in src/stubs/).

##### Elements

– CLI/Entry Point (rp2_main.py and country-specific executables)
– Input Loader & ODS Parser
– Configuration Loader
– Transaction Processors (in, intra, out transactions; accounting engine)
– Core Computation Modules (balance, gain_loss, computed_data, tax_engine)
– Plugin Manager with separate branches for Accounting Methods, Country Modules, and Report Generators
– Logger/Exception Handling modules
– Testing Suite (depicted as an external verification block)

– Start at the CLI, moving toward configuration and data parsing, then into the processing engine, branching into plugins, and finally, output generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        A1["CLI (rp2_main.py)"]:::cli
    end

    %% Input Processing Layer
    subgraph "Input Processing"
        B1["ODS Parser"]:::input
        B2["Configuration Loader"]:::input
        B3["Config Schema"]:::input
    end

    %% Core Processing Layer
    subgraph "Core Processing"
        C1["Accounting Engine"]:::core
        C2["In Transaction"]:::core
        C3["Intra Transaction"]:::core
        C4["Out Transaction"]:::core
        C5["Balance Module"]:::core
        C6["Gain/Loss Module"]:::core
        C7["Computed Data"]:::core
        C8["Tax Engine"]:::core
        C9["Transaction Set"]:::core
    end

    %% Plugin Architecture Layer
    subgraph "Plugin Architecture"
        D1["Accounting Methods Plugins"]:::plugin
        D2["Country Plugins"]:::plugin
        subgraph "Report Generator Plugins"
            D3["Report Core"]:::plugin
            D4["Report Data"]:::plugin
        end
    end

    %% Supporting Modules Layer
    subgraph "Supporting Modules"
        E1["Localization"]:::support
        E2["Logger"]:::support
        E3["Error Handling"]:::support
        E4["Testing Suite"]:::support
    end

    %% Relationships
    A1 -->|"invokes"| B1
    A1 -->|"invokes"| B2
    A1 -->|"invokes"| B3

    B1 -->|"provides data"| C1
    B2 -->|"provides config"| C1
    B3 -->|"provides schema"| C1

    C1 -->|"initializes"| C2
    C1 -->|"initializes"| C3
    C1 -->|"initializes"| C4
    C1 -->|"assembles"| C9
    C1 -->|"triggers"| C5
    C1 -->|"triggers"| C6
    C1 -->|"triggers"| C7
    C1 -->|"triggers"| C8

    C2 -->|"aggregates"| C9
    C3 -->|"aggregates"| C9
    C4 -->|"aggregates"| C9

    C8 -->|"loads plugin"| D1
    C8 -->|"loads plugin"| D2
    C8 -->|"generates report"| D3
    D3 -->|"uses data"| D4
    D3 -->|"localizes"| E1

    %% Logging
    A1 ---|"logs"| E2
    C1 ---|"logs"| E2
    C1 ---|"handles errors"| E3

    %% Testing
    E4 ---|"validates"| C1

    %% Click Events
    click A1 "https://github.com/eprbell/rp2/blob/main/src/rp2/rp2_main.py"
    click B1 "https://github.com/eprbell/rp2/blob/main/src/rp2/ods_parser.py"
    click B2 "https://github.com/eprbell/rp2/blob/main/src/rp2/configuration.py"
    click B3 "https://github.com/eprbell/rp2/blob/main/src/rp2/configuration_schema.py"
    click C1 "https://github.com/eprbell/rp2/blob/main/src/rp2/accounting_engine.py"
    click C2 "https://github.com/eprbell/rp2/blob/main/src/rp2/in_transaction.py"
    click C3 "https://github.com/eprbell/rp2/blob/main/src/rp2/intra_transaction.py"
    click C4 "https://github.com/eprbell/rp2/blob/main/src/rp2/out_transaction.py"
    click C5 "https://github.com/eprbell/rp2/blob/main/src/rp2/balance.py"
    click C6 "https://github.com/eprbell/rp2/blob/main/src/rp2/gain_loss.py"
    click C7 "https://github.com/eprbell/rp2/blob/main/src/rp2/computed_data.py"
    click C8 "https://github.com/eprbell/rp2/blob/main/src/rp2/tax_engine.py"
    click C9 "https://github.com/eprbell/rp2/blob/main/src/rp2/transaction_set.py"
    click D1 "https://github.com/eprbell/rp2/tree/main/src/rp2/plugin/accounting_method/"
    click D2 "https://github.com/eprbell/rp2/tree/main/src/rp2/plugin/country/"
    click D3 "https://github.com/eprbell/rp2/blob/main/src/rp2/plugin/report/abstract_ods_generator.py"
    click D4 "https://github.com/eprbell/rp2/tree/main/src/rp2/plugin/report/data/"
    click E1 "https://github.com/eprbell/rp2/tree/main/src/rp2/locales/"
    click E2 "https://github.com/eprbell/rp2/blob/main/src/rp2/logger.py"
    click E3 "https://github.com/eprbell/rp2/blob/main/src/rp2/rp2_error.py"
    click E4 "https://github.com/eprbell/rp2/tree/main/tests/"

    %% Styles
    classDef cli fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef input fill:#FFCC80,stroke:#333,stroke-width:2px;
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef plugin fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef support fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
