# praveenkumarv-github/portfolio architecture

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

- Interactive diagram: https://gitdiagram.com/praveenkumarv-github/portfolio
- Repository: https://github.com/praveenkumarv-github/portfolio

## Overview

This is a single-user Django personal-finance dashboard. An approved user accesses the dashboard through Cloudflare Access; they upload an XLSX workbook or provide a Google Sheet URL, after which the app validates and parses the workbook, resolves fund NAV and metal prices, computes portfolio metrics and alerts, and renders the results. The graph includes workbook import, look-through allocation, and net-worth snapshots as distinct product stages. Source excerpts show the main orchestration and dependencies; some documented runtime and security links rely on the README.

Main entry points: [`dashboard/views.py`](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/views.py) (Dashboard handlers), [`dashboard/services/aggregator.py`](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/aggregator.py) (Dashboard aggregator), [`dashboard/services/metal_price_service.py`](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/metal_price_service.py) (Metal price service), [`finance_dashboard/settings.py`](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/finance_dashboard/settings.py) (Django app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and UI"]
  node_cloudflare["Cloudflare Access"]
  node_django["Django app<br/>[settings.py]"]
  node_auth_middleware["Access JWT check<br/>[middleware.py]"]
  node_views["Dashboard handlers<br/>[views.py]"]
  node_dashboard_ui["Dashboard UI<br/>[dashboard.html]"]
end

subgraph group_imports["Workbook Import"]
  node_workbook_validation["Workbook validation"]
  node_google_sheets["Google Sheet import"]
  node_google_drive["Google Drive export"]
  node_excel_parser["Workbook parser<br/>[excel_parser.py]"]
  node_nav_service["Fund NAV lookup<br/>[nav_service.py]"]
end

subgraph group_finance["Portfolio Analytics"]
  node_aggregator["Dashboard aggregator<br/>[aggregator.py]"]
  node_calculation["Portfolio calculations"]
  node_economic_allocation["Look-through allocation"]
  node_alerts["Portfolio alerts<br/>[alerts.py]"]
  node_capital_gains["Fund transaction analytics<br/>[capital_gains.py]"]
  node_xirr["XIRR solver<br/>[xirr.py]"]
end

subgraph group_state["Prices and State"]
  node_metal_prices["Metal price service"]
  node_price_cache[("Metal price cache<br/>[metal_prices.json]")]
  node_records[("Upload and snapshots<br/>[models.py]")]
end

node_user(("Approved user"))
node_amfi["AMFI / MFAPI"]
node_goodreturns["GoodReturns"]

node_user -->|"signs in"| node_cloudflare
node_cloudflare -->|"forwards request"| node_django
node_django -->|"configures"| node_auth_middleware
node_django -->|"routes requests"| node_views
node_views -->|"renders"| node_dashboard_ui
node_views -->|"validates upload"| node_workbook_validation
node_views -->|"imports sheet"| node_google_sheets
node_google_sheets -->|"fetches private export"| node_google_drive
node_google_sheets -->|"validates download"| node_workbook_validation
node_views -->|"builds dashboard"| node_aggregator
node_aggregator -->|"parses workbook"| node_excel_parser
node_excel_parser -->|"resolves NAV"| node_nav_service
node_nav_service -->|"queries NAV"| node_amfi
node_excel_parser -->|"resolves metal prices"| node_metal_prices
node_aggregator -->|"builds portfolio"| node_calculation
node_aggregator -->|"builds allocation"| node_economic_allocation
node_aggregator -->|"runs alerts"| node_alerts
node_aggregator -->|"records snapshots"| node_records
node_calculation -.->|"uses transaction analytics"| node_capital_gains
node_calculation -.->|"solves returns"| node_xirr
node_metal_prices -->|"scrapes prices"| node_goodreturns
node_metal_prices -->|"reads and writes"| node_price_cache
node_views -->|"refreshes prices"| node_metal_prices

click node_django "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/finance_dashboard/settings.py"
click node_auth_middleware "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/finance_dashboard/middleware.py"
click node_views "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/views.py"
click node_dashboard_ui "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/templates/dashboard/dashboard.html"
click node_workbook_validation "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/workbook_validation.py"
click node_google_sheets "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/google_sheet_service.py"
click node_excel_parser "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/excel_parser.py"
click node_nav_service "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/nav_service.py"
click node_aggregator "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/aggregator.py"
click node_calculation "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/calculation_engine.py"
click node_economic_allocation "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/economic_allocation.py"
click node_alerts "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/alerts.py"
click node_capital_gains "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/capital_gains.py"
click node_xirr "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/xirr.py"
click node_metal_prices "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/metal_price_service.py"
click node_price_cache "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/data/metal_prices.json"
click node_records "https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/models.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_cloudflare,node_django,node_auth_middleware,node_views,node_dashboard_ui,node_user toneBlue
class node_workbook_validation,node_google_sheets,node_google_drive,node_excel_parser,node_nav_service toneAmber
class node_aggregator,node_calculation,node_economic_allocation,node_alerts,node_capital_gains,node_xirr,node_amfi toneMint
class node_metal_prices,node_price_cache,node_records toneRose
class node_goodreturns toneIndigo
```

## Components

### Access and UI

- **Cloudflare Access**
- [Django app](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/finance_dashboard/settings.py): `finance_dashboard/settings.py`
- [Access JWT check](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/finance_dashboard/middleware.py): `finance_dashboard/middleware.py`
- [Dashboard handlers](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/views.py): `dashboard/views.py`
- [Dashboard UI](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/templates/dashboard/dashboard.html): `dashboard/templates/dashboard/dashboard.html`

### Workbook Import

- [Workbook validation](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/workbook_validation.py): `dashboard/services/workbook_validation.py`
- [Google Sheet import](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/google_sheet_service.py): `dashboard/services/google_sheet_service.py`
- **Google Drive export**
- [Workbook parser](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/excel_parser.py): `dashboard/services/excel_parser.py`
- [Fund NAV lookup](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/nav_service.py): `dashboard/services/nav_service.py`

### Portfolio Analytics

- [Dashboard aggregator](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/aggregator.py): `dashboard/services/aggregator.py`
- [Portfolio calculations](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/calculation_engine.py): `dashboard/services/calculation_engine.py`
- [Look-through allocation](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/economic_allocation.py): `dashboard/services/economic_allocation.py`
- [Portfolio alerts](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/alerts.py): `dashboard/services/alerts.py`
- [Fund transaction analytics](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/capital_gains.py): `dashboard/services/capital_gains.py`
- [XIRR solver](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/xirr.py): `dashboard/services/xirr.py`

### Prices and State

- [Metal price service](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/services/metal_price_service.py): `dashboard/services/metal_price_service.py`
- [Metal price cache](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/data/metal_prices.json): `data/metal_prices.json`
- [Upload and snapshots](https://github.com/praveenkumarv-github/portfolio/blob/fea-v2/dashboard/models.py): `dashboard/models.py`

### Other components

- **Approved user**
- **AMFI / MFAPI**
- **GoodReturns**

## Connections

- Approved user → Cloudflare Access: signs in (evidence: `README.md`)
- Cloudflare Access → Django app: forwards request (evidence: `README.md`)
- Django app → Access JWT check: configures
- Django app → Dashboard handlers: routes requests (evidence: `README.md`)
- Dashboard handlers → Dashboard UI: renders (evidence: `README.md`)
- Dashboard handlers → Workbook validation: validates upload (evidence: `dashboard/views.py`)
- Dashboard handlers → Google Sheet import: imports sheet (evidence: `dashboard/views.py`)
- Google Sheet import → Google Drive export: fetches private export (evidence: `dashboard/services/google_sheet_service.py`)
- Google Sheet import → Workbook validation: validates download (evidence: `dashboard/services/google_sheet_service.py`)
- Dashboard handlers → Dashboard aggregator: builds dashboard (evidence: `dashboard/views.py`)
- Dashboard aggregator → Workbook parser: parses workbook (evidence: `dashboard/services/aggregator.py`)
- Workbook parser → Fund NAV lookup: resolves NAV (evidence: `dashboard/services/excel_parser.py`)
- Fund NAV lookup → AMFI / MFAPI: queries NAV (evidence: `README.md`)
- Workbook parser → Metal price service: resolves metal prices (evidence: `dashboard/services/excel_parser.py`)
- Dashboard aggregator → Portfolio calculations: builds portfolio (evidence: `dashboard/services/aggregator.py`)
- Dashboard aggregator → Look-through allocation: builds allocation (evidence: `dashboard/services/aggregator.py`)
- Dashboard aggregator → Portfolio alerts: runs alerts (evidence: `dashboard/services/aggregator.py`)
- Dashboard aggregator → Upload and snapshots: records snapshots (evidence: `dashboard/services/aggregator.py`)
- Portfolio calculations → Fund transaction analytics: uses transaction analytics (evidence: `dashboard/services/calculation_engine.py`)
- Portfolio calculations → XIRR solver: solves returns (evidence: `dashboard/services/calculation_engine.py`)
- Metal price service → GoodReturns: scrapes prices (evidence: `dashboard/services/metal_price_service.py`)
- Metal price service → Metal price cache: reads and writes (evidence: `dashboard/services/metal_price_service.py`)
- Dashboard handlers → Metal price service: refreshes prices (evidence: `dashboard/views.py`)
