# vnvarma39/paasa-taxalpha-engine architecture

> Architecture diagram of the GitHub repository vnvarma39/paasa-taxalpha-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vnvarma39/paasa-taxalpha-engine
- Repository: https://github.com/vnvarma39/paasa-taxalpha-engine

## Overview

Paasa TaxAlpha is a local-first tax analysis workspace for Indian investors with global holdings. The main workflow is to submit broker trades through the web interface, normalize them, calculate Indian-calendar gains and related tax opportunities, then review or export filing schedules. Separate analysis branches cover dividend tax credits, loss harvesting, UK comparisons, and UCITS exposure. The graph follows the README and sampled module responsibilities; some server pipeline wiring is inferred from the documented architecture, while unsampled implementation details are not expanded.

Main entry points: [`server.py`](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/server.py) (Flask API), [`static/index.html`](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/static/index.html) (Tax Dashboard), [`core/tax_engine.py`](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/tax_engine.py) (FIFO Tax Engine), [`core/currency.py`](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/currency.py) (Rule 115 FX)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web Interface"]
  node_web_ui["Tax Dashboard<br/>[index.html]"]
end

subgraph group_workflow["Analysis Workflow"]
  node_server["Flask API<br/>[server.py]"]
  node_parser["Trade Parser<br/>[parser.py]"]
end

subgraph group_engines["Tax Engines"]
  node_tax_engine["FIFO Tax Engine<br/>[tax_engine.py]"]
  node_currency["Rule 115 FX<br/>[currency.py]"]
  node_harvester["Loss Harvester<br/>[loss_harvester.py]"]
  node_dtaa["DTAA Reconciler<br/>[dtaa_reconciler.py]"]
  node_global_tax["Global Tax Comparison<br/>[global_tax.py]"]
  node_ucits["UCITS Optimizer<br/>[ucits_optimizer.py]"]
end

subgraph group_reporting["Reports and Data"]
  node_rates["SBI TT Rates"]
  node_substitutes["ETF Substitutes"]
  node_exporter["Report Exporter<br/>[exporter.py]"]
  node_sample_csv["Sample Portfolio"]
  node_excel_report["CA Workbook"]
end

node_investor(("Investor"))

node_investor -->|"submits trades"| node_web_ui
node_web_ui -->|"sends requests"| node_server
node_server -->|"returns analysis"| node_web_ui
node_server -->|"parses trades"| node_parser
node_server -->|"reads sample"| node_sample_csv
node_sample_csv -->|"provides trades"| node_parser
node_server -->|"analyzes trades"| node_tax_engine
node_tax_engine -->|"requests FX rates"| node_currency
node_currency -->|"loads rates"| node_rates
node_server -->|"finds loss candidates"| node_harvester
node_harvester -->|"loads mappings"| node_substitutes
node_server -->|"reconciles dividends"| node_dtaa
node_server -->|"compares jurisdictions"| node_global_tax
node_server -->|"optimizes ETF exposure"| node_ucits
node_server -->|"requests export"| node_exporter
node_exporter -->|"writes workbook"| node_excel_report

click node_web_ui "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/static/index.html"
click node_server "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/server.py"
click node_parser "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/parser.py"
click node_tax_engine "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/tax_engine.py"
click node_currency "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/currency.py"
click node_rates "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/data/sbi_tt_historical.json"
click node_harvester "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/loss_harvester.py"
click node_substitutes "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/data/etf_substitutes.json"
click node_dtaa "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/dtaa_reconciler.py"
click node_global_tax "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/global_tax.py"
click node_ucits "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/ucits_optimizer.py"
click node_exporter "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/exporter.py"
click node_sample_csv "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/data/sample_portfolio_ibkr.csv"
click node_excel_report "https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/exports/ca_taxalpha_report_demo.xlsx"

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_web_ui toneBlue
class node_server,node_parser toneAmber
class node_tax_engine,node_currency,node_harvester,node_dtaa,node_global_tax,node_ucits toneMint
class node_rates,node_substitutes,node_exporter,node_sample_csv,node_excel_report toneRose
class node_investor toneIndigo
```

## Components

### Web Interface

- [Tax Dashboard](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/static/index.html): `static/index.html`

### Analysis Workflow

- [Flask API](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/server.py): `server.py`
- [Trade Parser](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/parser.py): `core/parser.py`

### Tax Engines

- [FIFO Tax Engine](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/tax_engine.py): `core/tax_engine.py`
- [Rule 115 FX](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/currency.py): `core/currency.py`
- [Loss Harvester](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/loss_harvester.py): `core/loss_harvester.py`
- [DTAA Reconciler](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/dtaa_reconciler.py): `core/dtaa_reconciler.py`
- [Global Tax Comparison](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/global_tax.py): `core/global_tax.py`
- [UCITS Optimizer](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/ucits_optimizer.py): `core/ucits_optimizer.py`

### Reports and Data

- [SBI TT Rates](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/data/sbi_tt_historical.json): `data/sbi_tt_historical.json`
- [ETF Substitutes](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/data/etf_substitutes.json): `data/etf_substitutes.json`
- [Report Exporter](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/core/exporter.py): `core/exporter.py`
- [Sample Portfolio](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/data/sample_portfolio_ibkr.csv): `data/sample_portfolio_ibkr.csv`
- [CA Workbook](https://github.com/vnvarma39/paasa-taxalpha-engine/blob/main/exports/ca_taxalpha_report_demo.xlsx): `exports/ca_taxalpha_report_demo.xlsx`

### Other components

- **Investor**

## Connections

- Investor → Tax Dashboard: submits trades
- Tax Dashboard → Flask API: sends requests
- Flask API → Tax Dashboard: returns analysis
- Flask API → Trade Parser: parses trades
- Flask API → Sample Portfolio: reads sample
- Sample Portfolio → Trade Parser: provides trades
- Flask API → FIFO Tax Engine: analyzes trades
- FIFO Tax Engine → Rule 115 FX: requests FX rates
- Rule 115 FX → SBI TT Rates: loads rates
- Flask API → Loss Harvester: finds loss candidates
- Loss Harvester → ETF Substitutes: loads mappings
- Flask API → DTAA Reconciler: reconciles dividends
- Flask API → Global Tax Comparison: compares jurisdictions
- Flask API → UCITS Optimizer: optimizes ETF exposure
- Flask API → Report Exporter: requests export
- Report Exporter → CA Workbook: writes workbook