How dpaneda/ngtonic works
Project Type and Purpose
• Type: A CLI-based personal finance tool.
• Purpose: To allow users to import their ING bank movements (via Excel files), deduplicate and store the data locally (in a JSON file), and then provide various commands such as listing movements, plotting balance evolution, grouping movements by month, and heuristically identifying regular bills.
File Structure
• Top-level Directories/Files:
• .github: Contains CI/CD workflows, dependency updates, and release configurations.
• scripts: Includes shell scripts for code formatting and linting.
• src/ngtonic: Contains the core Python modules.
▸ __main__.py: Likely serves as the entry point for the CLI execution.
▸ bills.py, movements.py, plotter.py, printer.py: Each of these modules handles a specific responsibility such as processing bills, handling movement data, generating plots, and printing formatted output.
• Configuration and dependency files (pyproject.toml, pdm.lock) indicate usage of modern Python project management with PDM.
• Additional Elements:
• The examples directory contains sample output images, evidencing the plotting functionality.
• Dockerfile and other CI/CD configurations illustrate support for containerization and continuous integration.
Key Architectural Insights from the README
• There’s a clear separation between data import, processing, and visual output.
• Commands (like “import”, “list”, “balance-plot”, etc.) suggest a command dispatcher mechanism that routing commands from the CLI to the appropriate module.
• The tool saves data locally (e.g., movements stored as .ngtonic/movements.json) and uses a configuration file (.ngtonic/config.yaml) for filtering out transactions.
Components and Their Interactions
• CLI/Entry Point:
• Represented by src/ngtonic/__main__.py.
• Acts as the interface for invoking different commands.
• Command Dispatcher/Router:
• This component interprets user commands ("import", "list", "balance-plot", "month-plot", "find-bills") and forwards them to the corresponding functional modules.
• Data Importer & Parser:
• Likely encapsulated in the movements.py module.
• Reads Excel files (e.g., movements.xls), extracts data and handles deduplication.
• Data Store / Local Storage:
• The processed movement data is saved locally (e.g., in the .ngtonic/movements.json file).
• This component is responsible for persistence.
• Data Analysis & Filtering:
• Modules like bills.py might contain heuristics to detect recurring bills.
• Processes the imported data based on rules (see configuration in .ngtonic/config.yaml) to filter or exclude certain transactions.
• Presentation/Output:
• The printer.py module is used for formatting terminal outputs (e.g., commands like “list”).
• The plotter.py module handles generation of graphs (balance evolution, monthly breakdowns), interfacing with plotting libraries.
• Configuration Manager:
• Reads and parses the configuration file (.ngtonic/config.yaml) to influence the filtering of movements.
• CI/CD and Development Tools:
• While not part of the runtime architecture, the presence of GitHub workflows, pre-commit hooks, Dockerfile, and scripts indicate robust development practices and testing.
Architectural Patterns & Design Principles
• Modularity: Each Python module in src/ngtonic (e.g., bills, movements, plotter, printer) addresses a specific aspect of the functionality.
• Separation of Concerns: The CLI layer is separated from business logic (data import, filtering, plotting) and from data storage.
• Command Pattern: The main executable (__main__.py) routes user commands to their respective handlers.
• Local Persistence: Data is stored locally in JSON format after processing.