# amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting architecture

> Architecture diagram of the GitHub repository amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting
- Repository: https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting

## Overview

This repository implements a personal financial digital twin: it turns Czech bank transactions into monthly account features, predicts next-month debit spending, and presents forecasts, explanations, counterfactuals, savings planning, and exports in a web dashboard. The main runtime path is browser → REST API → validated inference; simulation and explanations delegate to the same prediction gateway. The README documents workspace capabilities not fully visible in the excerpts; those are represented without inferring their internal wiring. Evidence for API delegation and feature derivation is available in excerpts; training and some UI details are not sampled.

Main entry points: [`src/app/api/server.py`](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/api/server.py) (REST API), [`src/app/static/app.js`](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/static/app.js) (Twin dashboard), [`src/models/models.py`](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/models/models.py) (CatBoost forecast), [`src/app/inference.py`](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/inference.py) (Prediction gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_raw[("Berka transactions")]
  node_loader["Raw table loader<br/>[loader.py]"]
  node_preprocessor["Monthly aggregation<br/>[preprocessor.py]"]
  node_panel[("Account-month panel")]
  node_features["Supervised features<br/>[builder.py]"]
  node_dataset[("Spending dataset")]
end

subgraph group_ml["Forecasting model"]
  node_model["CatBoost forecast<br/>[models.py]"]
  node_evaluation["Chronological evaluation<br/>[evaluator.py]"]
  node_globalxai["Global explainability<br/>[explainability.py]"]
end

subgraph group_runtime["Twin services"]
  node_schema["State validation<br/>[schema.py]"]
  node_inference["Prediction gateway<br/>[inference.py]"]
  node_simulator["What-if simulator<br/>[simulator.py]"]
  node_explainer["Local TreeSHAP<br/>[explainer.py]"]
  node_export["PDF and Excel export<br/>[export.py]"]
end

subgraph group_presentation["Web experience"]
  node_browser["Twin dashboard<br/>[app.js]"]
  node_api["REST API<br/>[server.py]"]
  node_goal["Savings goal planner<br/>[app.js]"]
  node_planner["Financial action planner<br/>[app.js]"]
end

node_user(("Financial user"))

node_user -->|"uses"| node_browser
node_browser -.->|"requests"| node_api
node_raw -->|"loads"| node_loader
node_loader -.->|"provides tables"| node_preprocessor
node_preprocessor -->|"aggregates"| node_panel
node_panel -->|"builds features"| node_features
node_features -->|"produces"| node_dataset
node_dataset -->|"partitions"| node_evaluation
node_dataset -.->|"trains"| node_model
node_model -.->|"evaluated by"| node_evaluation
node_model -.->|"explained by"| node_globalxai
node_api -->|"validates request"| node_schema
node_api -->|"predicts via"| node_inference
node_api -->|"simulates via"| node_simulator
node_api -->|"explains via"| node_explainer
node_api -->|"generates exports"| node_export
node_inference -->|"derives features"| node_schema
node_inference -.->|"runs prediction"| node_model
node_simulator -->|"predicts scenarios"| node_inference
node_simulator -->|"validates states"| node_schema
node_explainer -->|"gets forecast"| node_inference
node_explainer -.->|"explains prediction"| node_model
node_browser -->|"plans savings"| node_goal
node_browser -->|"synthesizes guidance"| node_planner
node_browser -->|"requests downloads"| node_export

click node_raw "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/tree/main/data/raw/berka"
click node_loader "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/data/loader.py"
click node_preprocessor "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/data/preprocessor.py"
click node_panel "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/data/processed/account_monthly_panel.csv"
click node_features "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/features/builder.py"
click node_dataset "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/data/processed/supervised_spending_dataset.csv"
click node_model "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/models/models.py"
click node_evaluation "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/models/evaluator.py"
click node_globalxai "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/models/explainability.py"
click node_browser "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/static/app.js"
click node_api "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/api/server.py"
click node_schema "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/schema.py"
click node_inference "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/inference.py"
click node_simulator "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/simulator.py"
click node_explainer "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/explainer.py"
click node_goal "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/static/app.js"
click node_planner "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/static/app.js"
click node_export "https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/export.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_raw,node_loader,node_preprocessor,node_panel,node_features,node_dataset,node_user toneBlue
class node_model,node_evaluation,node_globalxai toneAmber
class node_schema,node_inference,node_simulator,node_explainer,node_export toneMint
class node_browser,node_api,node_goal,node_planner toneRose
```

## Components

### Data preparation

- [Berka transactions](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/tree/main/data/raw/berka): `data/raw/berka`
- [Raw table loader](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/data/loader.py): `src/data/loader.py`
- [Monthly aggregation](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/data/preprocessor.py): `src/data/preprocessor.py`
- [Account-month panel](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/data/processed/account_monthly_panel.csv): `data/processed/account_monthly_panel.csv`
- [Supervised features](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/features/builder.py): `src/features/builder.py`
- [Spending dataset](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/data/processed/supervised_spending_dataset.csv): `data/processed/supervised_spending_dataset.csv`

### Forecasting model

- [CatBoost forecast](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/models/models.py): `src/models/models.py`
- [Chronological evaluation](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/models/evaluator.py): `src/models/evaluator.py`
- [Global explainability](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/models/explainability.py): `src/models/explainability.py`

### Twin services

- [State validation](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/schema.py): `src/app/schema.py`
- [Prediction gateway](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/inference.py): `src/app/inference.py`
- [What-if simulator](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/simulator.py): `src/app/simulator.py`
- [Local TreeSHAP](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/explainer.py): `src/app/explainer.py`
- [PDF and Excel export](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/export.py): `src/app/export.py`

### Web experience

- [Twin dashboard](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/static/app.js): `src/app/static/app.js`
- [REST API](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/api/server.py): `src/app/api/server.py`
- [Savings goal planner](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/static/app.js): `src/app/static/app.js`
- [Financial action planner](https://github.com/amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting/blob/main/src/app/static/app.js): `src/app/static/app.js`

### Other components

- **Financial user**

## Connections

- Financial user → Twin dashboard: uses (evidence: `README.md`)
- Twin dashboard → REST API: requests
- Berka transactions → Raw table loader: loads (evidence: `src/data/loader.py`)
- Raw table loader → Monthly aggregation: provides tables
- Monthly aggregation → Account-month panel: aggregates (evidence: `src/data/preprocessor.py`)
- Account-month panel → Supervised features: builds features (evidence: `src/features/builder.py`)
- Supervised features → Spending dataset: produces (evidence: `src/features/builder.py`)
- Spending dataset → Chronological evaluation: partitions (evidence: `README.md`)
- Spending dataset → CatBoost forecast: trains
- CatBoost forecast → Chronological evaluation: evaluated by
- CatBoost forecast → Global explainability: explained by
- REST API → State validation: validates request (evidence: `src/app/api/server.py`)
- REST API → Prediction gateway: predicts via (evidence: `src/app/api/server.py`)
- REST API → What-if simulator: simulates via (evidence: `src/app/api/server.py`)
- REST API → Local TreeSHAP: explains via (evidence: `src/app/api/server.py`)
- REST API → PDF and Excel export: generates exports (evidence: `src/app/api/server.py`)
- Prediction gateway → State validation: derives features (evidence: `src/app/inference.py`)
- Prediction gateway → CatBoost forecast: runs prediction
- What-if simulator → Prediction gateway: predicts scenarios (evidence: `src/app/simulator.py`)
- What-if simulator → State validation: validates states (evidence: `src/app/simulator.py`)
- Local TreeSHAP → Prediction gateway: gets forecast (evidence: `src/app/explainer.py`)
- Local TreeSHAP → CatBoost forecast: explains prediction
- Twin dashboard → Savings goal planner: plans savings (evidence: `README.md`)
- Twin dashboard → Financial action planner: synthesizes guidance (evidence: `README.md`)
- Twin dashboard → PDF and Excel export: requests downloads (evidence: `README.md`)
