# pennypenny135-coder/mpf-comparison architecture

> Architecture diagram of the GitHub repository pennypenny135-coder/mpf-comparison, 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/pennypenny135-coder/mpf-comparison
- Repository: https://github.com/pennypenny135-coder/mpf-comparison

## Overview

This is a browser-based MPF fund-return analyzer. Users load the sample workbook or upload an Excel file, review parsed data, choose return periods and filters, then compare fund returns and trustee rankings or export CSVs. The main page owns dataset loading, persistence and composition of the analysis controls; a separate statistics page presents trustee-oriented analysis. The graph reflects the sampled calls and documented page behavior; several listed UI components and the database files were not sampled, so their runtime connections are omitted.

Main entry points: [`src/app/page.tsx`](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/app/page.tsx) (Fund analysis), [`src/lib/returns.ts`](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/lib/returns.ts) (Return calculations), [`src/app/stats/page.tsx`](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/app/stats/page.tsx) (Trustee statistics), [`src/components/fund-table.tsx`](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/fund-table.tsx) (Fund results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Application pages"]
  node_home["Fund analysis<br/>[page.tsx]"]
  node_stats["Trustee statistics<br/>[page.tsx]"]
  node_about["About page<br/>[page.tsx]"]
end

subgraph group_controls["Analysis interface"]
  node_upload["Workbook upload<br/>[upload-panel.tsx]"]
  node_filters["Fund filters<br/>[filter-panel.tsx]"]
  node_periods["Period controls"]
  node_fundtable["Fund results<br/>[fund-table.tsx]"]
  node_trusteeview["Trustee results<br/>[trustee-stats.tsx]"]
  node_distribution["Plan distribution"]
  node_sampledl["Sample download"]
  node_theme["Theme toggle<br/>[theme-toggle.tsx]"]
end

subgraph group_domain["Parsing and returns"]
  node_parser["Excel parser<br/>[excel-parser.ts]"]
  node_returns["Return calculations<br/>[returns.ts]"]
  node_types["MPF data model<br/>[mpf.ts]"]
end

subgraph group_persistence["Data and export"]
  node_storage[("Browser dataset storage<br/>[storage.ts]")]
  node_csv["CSV export<br/>[csv-export.ts]"]
end

node_user(("Analyst"))
node_sample["Sample workbook"]

node_user -->|"analyzes funds"| node_home
node_home -->|"parses sample"| node_parser
node_home -->|"loads and saves"| node_storage
node_home -->|"generates periods"| node_returns
node_home -->|"renders upload"| node_upload
node_home -->|"renders filters"| node_filters
node_home -->|"renders controls"| node_periods
node_home -->|"renders results"| node_fundtable
node_home -->|"renders statistics"| node_trusteeview
node_home -->|"fetches workbook"| node_sample
node_upload -->|"parses uploads"| node_parser
node_stats -->|"loads dataset"| node_storage
node_stats -->|"parses sample"| node_parser
node_stats -->|"fetches workbook"| node_sample
node_stats -->|"gets fund categories"| node_returns
node_periods -->|"builds periods"| node_returns
node_fundtable -->|"exports fund rows"| node_csv
node_fundtable -->|"uses period keys"| node_returns
node_trusteeview -->|"computes rankings"| node_returns
node_trusteeview -->|"exports statistics"| node_csv
node_csv -->|"uses period keys"| node_returns

click node_home "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/app/page.tsx"
click node_stats "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/app/stats/page.tsx"
click node_about "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/app/about/page.tsx"
click node_upload "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/upload-panel.tsx"
click node_filters "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/filter-panel.tsx"
click node_periods "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/period-controls.tsx"
click node_fundtable "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/fund-table.tsx"
click node_trusteeview "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/trustee-stats.tsx"
click node_distribution "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/plan-distribution-table.tsx"
click node_sampledl "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/sample-download.tsx"
click node_theme "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/theme-toggle.tsx"
click node_parser "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/lib/excel-parser.ts"
click node_returns "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/lib/returns.ts"
click node_types "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/types/mpf.ts"
click node_storage "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/lib/storage.ts"
click node_csv "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/lib/csv-export.ts"
click node_sample "https://github.com/pennypenny135-coder/mpf-comparison/blob/main/public/Sample/Fund_Information_Table_result-2.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_home,node_stats,node_about toneBlue
class node_upload,node_filters,node_periods,node_fundtable,node_trusteeview,node_distribution,node_sampledl,node_theme toneAmber
class node_parser,node_returns,node_types toneMint
class node_storage,node_csv toneRose
class node_user toneIndigo
class node_sample toneTeal
```

## Components

### Application pages

- [Fund analysis](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Trustee statistics](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/app/stats/page.tsx): `src/app/stats/page.tsx`
- [About page](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/app/about/page.tsx): `src/app/about/page.tsx`

### Analysis interface

- [Workbook upload](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/upload-panel.tsx): `src/components/upload-panel.tsx`
- [Fund filters](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/filter-panel.tsx): `src/components/filter-panel.tsx`
- [Period controls](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/period-controls.tsx): `src/components/period-controls.tsx`
- [Fund results](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/fund-table.tsx): `src/components/fund-table.tsx`
- [Trustee results](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/trustee-stats.tsx): `src/components/trustee-stats.tsx`
- [Plan distribution](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/plan-distribution-table.tsx): `src/components/plan-distribution-table.tsx`
- [Sample download](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/sample-download.tsx): `src/components/sample-download.tsx`
- [Theme toggle](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/components/theme-toggle.tsx): `src/components/theme-toggle.tsx`

### Parsing and returns

- [Excel parser](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/lib/excel-parser.ts): `src/lib/excel-parser.ts`
- [Return calculations](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/lib/returns.ts): `src/lib/returns.ts`
- [MPF data model](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/types/mpf.ts): `src/types/mpf.ts`

### Data and export

- [Browser dataset storage](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/lib/storage.ts): `src/lib/storage.ts`
- [CSV export](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/src/lib/csv-export.ts): `src/lib/csv-export.ts`

### Other components

- **Analyst**
- [Sample workbook](https://github.com/pennypenny135-coder/mpf-comparison/blob/main/public/Sample/Fund_Information_Table_result-2.xlsx): `public/Sample/Fund_Information_Table_result-2.xlsx`

## Connections

- Analyst → Fund analysis: analyzes funds
- Fund analysis → Excel parser: parses sample (evidence: `src/app/page.tsx`)
- Fund analysis → Browser dataset storage: loads and saves (evidence: `src/app/page.tsx`)
- Fund analysis → Return calculations: generates periods (evidence: `src/app/page.tsx`)
- Fund analysis → Workbook upload: renders upload (evidence: `src/app/page.tsx`)
- Fund analysis → Fund filters: renders filters (evidence: `src/app/page.tsx`)
- Fund analysis → Period controls: renders controls (evidence: `src/app/page.tsx`)
- Fund analysis → Fund results: renders results (evidence: `src/app/page.tsx`)
- Fund analysis → Trustee results: renders statistics (evidence: `src/app/page.tsx`)
- Fund analysis → Sample workbook: fetches workbook (evidence: `src/app/page.tsx`)
- Workbook upload → Excel parser: parses uploads (evidence: `src/components/upload-panel.tsx`)
- Trustee statistics → Browser dataset storage: loads dataset (evidence: `src/app/stats/page.tsx`)
- Trustee statistics → Excel parser: parses sample (evidence: `src/app/stats/page.tsx`)
- Trustee statistics → Sample workbook: fetches workbook (evidence: `src/app/stats/page.tsx`)
- Trustee statistics → Return calculations: gets fund categories (evidence: `src/app/stats/page.tsx`)
- Period controls → Return calculations: builds periods (evidence: `src/components/period-controls.tsx`)
- Fund results → CSV export: exports fund rows (evidence: `src/components/fund-table.tsx`)
- Fund results → Return calculations: uses period keys (evidence: `src/components/fund-table.tsx`)
- Trustee results → Return calculations: computes rankings (evidence: `src/components/trustee-stats.tsx`)
- Trustee results → CSV export: exports statistics (evidence: `src/components/trustee-stats.tsx`)
- CSV export → Return calculations: uses period keys (evidence: `src/lib/csv-export.ts`)
