# dpaneda/ngtonic architecture

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

- Interactive diagram: https://gitdiagram.com/dpaneda/ngtonic
- Repository: https://github.com/dpaneda/ngtonic

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core CLI and Command Dispatcher
    A["CLI/Entry Point"]:::cli
    B["Command Dispatcher"]:::dispatcher

    %% Business Logic Modules
    C["Data Importer & Parser"]:::logic
    D["Data Analysis & Filtering (Recurring Bills)"]:::logic
    E["Terminal Output (Printing)"]:::presentation
    F["Plot Generation"]:::presentation

    %% Data Persistence and Configuration
    G(["Local Data Store (.ngtonic/movements.json)"]):::storage
    H["Configuration Manager (.ngtonic/config.yaml)"]:::config

    %% Development Tools Subgraph
    subgraph "Development Tools"
        I[".github"]:::dev
        J["scripts (format.sh, lint.sh)"]:::dev
    end

    %% Flow Connections
    A -->|"invokes"| B
    B -->|"import command"| C
    C -->|"saves data to"| G
    B -->|"list command"| E
    B -->|"plot command"| F
    B -->|"bill detection"| D

    %% Data store feeding output modules
    G -->|"data for listing"| E
    G -->|"data for plotting"| F
    G -->|"data for analysis"| D

    %% Configuration influences analysis
    H -->|"filter rules"| D

    %% Styles
    classDef cli fill:#f2c94c,stroke:#333,stroke-width:2px;
    classDef dispatcher fill:#56cc9d,stroke:#333,stroke-width:2px;
    classDef logic fill:#56a0d3,stroke:#333,stroke-width:2px;
    classDef presentation fill:#f2994a,stroke:#333,stroke-width:2px;
    classDef storage fill:#bb6bd9,stroke:#333,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef config fill:#9b51e0,stroke:#333,stroke-width:2px,stroke-dasharray: 2, 2;
    classDef dev fill:#27ae60,stroke:#333,stroke-width:2px;

    %% Click Events
    click A "https://github.com/dpaneda/ngtonic/blob/main/src/ngtonic/__main__.py"
    click C "https://github.com/dpaneda/ngtonic/blob/main/src/ngtonic/movements.py"
    click D "https://github.com/dpaneda/ngtonic/blob/main/src/ngtonic/bills.py"
    click E "https://github.com/dpaneda/ngtonic/blob/main/src/ngtonic/printer.py"
    click F "https://github.com/dpaneda/ngtonic/blob/main/src/ngtonic/plotter.py"
    click I "https://github.com/dpaneda/ngtonic/blob/main/.github"
    click J "https://github.com/dpaneda/ngtonic/tree/main/scripts"
```
