# traynertunder2047/financeflow architecture

> Architecture diagram of the GitHub repository traynertunder2047/financeflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/traynertunder2047/financeflow
- Repository: https://github.com/traynertunder2047/financeflow

## Overview

FinanceFlow is an interactive CLI planner: users choose an AI or job-posting salary search, provide job and country details, review an estimated after-tax salary, enter monthly expenses, and allocate remaining savings to objectives. Tax estimation uses cached brackets or extracts them from the OECD PDF, falling back to AI web research, then converts currencies as needed. Spending and objective calculations are implemented in the main flow and reported through the UI. Source excerpts show the main calls and tax pipeline; README documents capabilities whose internal implementation was not sampled.

Main entry points: [`main.py`](https://github.com/traynertunder2047/financeflow/blob/main/main.py) (Workflow Orchestrator), [`app/taxCalculator.py`](https://github.com/traynertunder2047/financeflow/blob/main/app/taxCalculator.py) (Tax Calculation), [`app/scraper.py`](https://github.com/traynertunder2047/financeflow/blob/main/app/scraper.py) (Salary Search Modes), [`app/pdfChapterExtractor.py`](https://github.com/traynertunder2047/financeflow/blob/main/app/pdfChapterExtractor.py) (PDF Chapter Extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["CLI Workflow"]
  node_main["Workflow Orchestrator<br/>[main.py]"]
  node_ui["Prompts and Reports<br/>[ui.py]"]
  node_spending["Spending Profile<br/>[main.py]"]
  node_objectives["Objective Allocation<br/>[main.py]"]
end

subgraph group_salary["Salary Research"]
  node_salary_search["Salary Search Modes<br/>[scraper.py]"]
  node_tax_params["Web Bracket Search<br/>[scraper.py]"]
  node_tax_math["Bracket Tax Math<br/>[scraper.py]"]
end

subgraph group_tax["Tax Estimation"]
  node_tax["Tax Calculation<br/>[taxCalculator.py]"]
  node_pdf_chapter["PDF Chapter Extraction"]
  node_pdf_params["PDF Bracket Extraction"]
end

subgraph group_support["Rates and Cache"]
  node_tax_cache[("Tax Parameter Cache")]
  node_currency["Currency Conversion"]
  node_rates[("Exchange Rate Cache<br/>[exchangeRates.json]")]
end

node_user(("Planner"))
node_jobdatalake{{"Jobdatalake API"}}
node_gemini{{"Gemini Search"}}
node_pdf["OECD Tax PDF"]
node_chapter_map["Country Chapter Map"]
node_fx_api{{"Exchange Rate API"}}

node_user -->|"enters workflow"| node_main
node_main -->|"prompts and reports"| node_ui
node_main -->|"requests salary"| node_salary_search
node_main -->|"requests tax"| node_tax
node_main -->|"collects expenses"| node_spending
node_spending -->|"supplies savings"| node_objectives
node_main -->|"plans goals"| node_objectives
node_salary_search -->|"queries postings"| node_jobdatalake
node_salary_search -->|"searches salary"| node_gemini
node_tax -->|"reads and writes"| node_tax_cache
node_tax -->|"extracts chapter"| node_pdf_chapter
node_pdf_chapter -->|"reads pages"| node_pdf
node_pdf_chapter -->|"loads map"| node_chapter_map
node_tax -->|"extracts brackets"| node_pdf_params
node_tax -->|"searches brackets"| node_tax_params
node_tax -->|"calculates tax"| node_tax_math
node_tax_math -->|"converts currency"| node_currency
node_currency -->|"reads and writes"| node_rates
node_currency -->|"fetches rates"| node_fx_api
node_tax_params -->|"searches brackets"| node_gemini

click node_main "https://github.com/traynertunder2047/financeflow/blob/main/main.py"
click node_ui "https://github.com/traynertunder2047/financeflow/blob/main/app/ui.py"
click node_spending "https://github.com/traynertunder2047/financeflow/blob/main/main.py"
click node_objectives "https://github.com/traynertunder2047/financeflow/blob/main/main.py"
click node_salary_search "https://github.com/traynertunder2047/financeflow/blob/main/app/scraper.py"
click node_tax "https://github.com/traynertunder2047/financeflow/blob/main/app/taxCalculator.py"
click node_pdf_chapter "https://github.com/traynertunder2047/financeflow/blob/main/app/pdfChapterExtractor.py"
click node_pdf_params "https://github.com/traynertunder2047/financeflow/blob/main/app/pdfParamExtractor.py"
click node_tax_params "https://github.com/traynertunder2047/financeflow/blob/main/app/scraper.py"
click node_tax_math "https://github.com/traynertunder2047/financeflow/blob/main/app/scraper.py"
click node_pdf "https://github.com/traynertunder2047/financeflow/blob/main/data/TaxingWages2026.pdf"
click node_chapter_map "https://github.com/traynertunder2047/financeflow/blob/main/data/countryChapters.json"
click node_tax_cache "https://github.com/traynertunder2047/financeflow/blob/main/data/fiscalCacheParams.json"
click node_currency "https://github.com/traynertunder2047/financeflow/blob/main/app/currencyConverter.py"
click node_rates "https://github.com/traynertunder2047/financeflow/blob/main/data/exchangeRates.json"

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_main,node_ui,node_spending,node_objectives toneBlue
class node_salary_search,node_tax_params,node_tax_math toneAmber
class node_tax,node_pdf_chapter,node_pdf_params,node_jobdatalake,node_fx_api toneMint
class node_tax_cache,node_currency,node_rates toneRose
class node_user,node_gemini toneIndigo
class node_pdf,node_chapter_map toneTeal
```

## Components

### CLI Workflow

- [Workflow Orchestrator](https://github.com/traynertunder2047/financeflow/blob/main/main.py): `main.py`
- [Prompts and Reports](https://github.com/traynertunder2047/financeflow/blob/main/app/ui.py): `app/ui.py`
- [Spending Profile](https://github.com/traynertunder2047/financeflow/blob/main/main.py): `main.py`
- [Objective Allocation](https://github.com/traynertunder2047/financeflow/blob/main/main.py): `main.py`

### Salary Research

- [Salary Search Modes](https://github.com/traynertunder2047/financeflow/blob/main/app/scraper.py): `app/scraper.py`
- [Web Bracket Search](https://github.com/traynertunder2047/financeflow/blob/main/app/scraper.py): `app/scraper.py`
- [Bracket Tax Math](https://github.com/traynertunder2047/financeflow/blob/main/app/scraper.py): `app/scraper.py`

### Tax Estimation

- [Tax Calculation](https://github.com/traynertunder2047/financeflow/blob/main/app/taxCalculator.py): `app/taxCalculator.py`
- [PDF Chapter Extraction](https://github.com/traynertunder2047/financeflow/blob/main/app/pdfChapterExtractor.py): `app/pdfChapterExtractor.py`
- [PDF Bracket Extraction](https://github.com/traynertunder2047/financeflow/blob/main/app/pdfParamExtractor.py): `app/pdfParamExtractor.py`

### Rates and Cache

- [Tax Parameter Cache](https://github.com/traynertunder2047/financeflow/blob/main/data/fiscalCacheParams.json): `data/fiscalCacheParams.json`
- [Currency Conversion](https://github.com/traynertunder2047/financeflow/blob/main/app/currencyConverter.py): `app/currencyConverter.py`
- [Exchange Rate Cache](https://github.com/traynertunder2047/financeflow/blob/main/data/exchangeRates.json): `data/exchangeRates.json`

### Other components

- **Planner**
- **Jobdatalake API**
- **Gemini Search**
- [OECD Tax PDF](https://github.com/traynertunder2047/financeflow/blob/main/data/TaxingWages2026.pdf): `data/TaxingWages2026.pdf`
- [Country Chapter Map](https://github.com/traynertunder2047/financeflow/blob/main/data/countryChapters.json): `data/countryChapters.json`
- **Exchange Rate API**

## Connections

- Planner → Workflow Orchestrator: enters workflow (evidence: `readme.md`)
- Workflow Orchestrator → Prompts and Reports: prompts and reports (evidence: `main.py`)
- Workflow Orchestrator → Salary Search Modes: requests salary (evidence: `main.py`)
- Workflow Orchestrator → Tax Calculation: requests tax (evidence: `main.py`)
- Workflow Orchestrator → Spending Profile: collects expenses (evidence: `main.py`)
- Spending Profile → Objective Allocation: supplies savings (evidence: `main.py`)
- Workflow Orchestrator → Objective Allocation: plans goals (evidence: `main.py`)
- Salary Search Modes → Jobdatalake API: queries postings (evidence: `app/scraper.py`)
- Salary Search Modes → Gemini Search: searches salary (evidence: `app/scraper.py`)
- Tax Calculation → Tax Parameter Cache: reads and writes (evidence: `app/taxCalculator.py`)
- Tax Calculation → PDF Chapter Extraction: extracts chapter (evidence: `app/taxCalculator.py`)
- PDF Chapter Extraction → OECD Tax PDF: reads pages (evidence: `app/pdfChapterExtractor.py`)
- PDF Chapter Extraction → Country Chapter Map: loads map (evidence: `app/pdfChapterExtractor.py`)
- Tax Calculation → PDF Bracket Extraction: extracts brackets (evidence: `app/taxCalculator.py`)
- Tax Calculation → Web Bracket Search: searches brackets (evidence: `app/taxCalculator.py`)
- Tax Calculation → Bracket Tax Math: calculates tax (evidence: `app/taxCalculator.py`)
- Bracket Tax Math → Currency Conversion: converts currency (evidence: `app/scraper.py`)
- Currency Conversion → Exchange Rate Cache: reads and writes (evidence: `app/currencyConverter.py`)
- Currency Conversion → Exchange Rate API: fetches rates (evidence: `app/currencyConverter.py`)
- Web Bracket Search → Gemini Search: searches brackets (evidence: `app/scraper.py`)
