How eprbell/rp2 works
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.