# stephin-mathew/mern-portfolio-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/stephin-mathew/mern-portfolio-tracker
- Repository: https://github.com/stephin-mathew/mern-portfolio-tracker

## Overview

This is an AI-assisted crypto and stock portfolio tracker. A signed-in user views a dashboard or analytics, manages wallets and holdings, and can upload a screenshot or JSON for extraction, review, and saving. The client’s App coordinates initial portfolio loading; the Express API routes requests to domain handlers and MongoDB-backed models. Pricing and extraction are distinct service stages. Source excerpts show key orchestration and dependencies; several page, route, and service implementations were not sampled, so uncertain connections are omitted.

Main entry points: [`server/src/index.js`](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/index.js) (Express API), [`client/src/App.jsx`](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/App.jsx) (App coordinator), [`server/src/services/extraction/extractionPipeline.js`](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/extractionPipeline.js) (Extraction pipeline), [`server/src/routes/prices.js`](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/routes/prices.js) (Price routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Portfolio client"]
  node_app["App coordinator<br/>[App.jsx]"]
  node_authctx["Authentication state<br/>[AuthContext.jsx]"]
  node_walletctx["Wallet state<br/>[WalletContext.jsx]"]
  node_api_client["API client<br/>[axiosInstance.js]"]
  node_dashboard["Dashboard<br/>[DashboardPage.jsx]"]
  node_analytics["Portfolio analytics<br/>[AnalyticsPage.jsx]"]
  node_walletpages["Wallet views<br/>[WalletsPage.jsx]"]
  node_walletdetail["Wallet detail"]
  node_holdings_ui["Holdings table<br/>[HoldingsTable.jsx]"]
  node_extract_ui["Extraction review"]
end

subgraph group_api["API and identity"]
  node_server["Express API<br/>[index.js]"]
  node_authmw["Auth middleware<br/>[auth.js]"]
  node_authroute["Auth routes<br/>[auth.js]"]
  node_user_model[("User store<br/>[User.js]")]
end

subgraph group_domain["Portfolio data"]
  node_holdingroute["Holdings routes<br/>[holdings.js]"]
  node_walletroute["Wallet routes<br/>[wallets.js]"]
  node_holdingmodel[("Holdings store<br/>[Holding.js]")]
  node_walletmodel[("Wallet store<br/>[Wallet.js]")]
end

subgraph group_services["Pricing and extraction"]
  node_priceroute["Price routes<br/>[prices.js]"]
  node_extractroute["Extraction route<br/>[extract.js]"]
  node_pipeline["Extraction pipeline"]
  node_extractvalidate["Result validation"]
  node_vision["Gemini extraction<br/>[geminiExtract.js]"]
  node_ocr["OCR extraction<br/>[ocrExtract.js]"]
  node_groq["Groq extraction<br/>[groqExtract.js]"]
  node_openrouter["OpenRouter extraction"]
  node_pricesvc["Price service<br/>[priceService.js]"]
  node_pricecache[("Price cache<br/>[PriceCache.js]")]
  node_priceoverride[("Price overrides<br/>[PriceOverride.js]")]
end

node_user(("Portfolio user"))
node_mongodb[("MongoDB")]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_analytics
node_app -->|"routes to"| node_walletpages
node_app -->|"routes to"| node_walletdetail
node_app -->|"fetches holdings and prices"| node_api_client
node_app -->|"orchestrates wallet fetch"| node_walletctx
node_authctx -->|"provides auth token"| node_api_client
node_walletctx -->|"fetches wallets"| node_api_client
node_dashboard -->|"renders"| node_holdings_ui
node_walletdetail -->|"renders"| node_holdings_ui
node_extract_ui -->|"fetches review prices"| node_api_client
node_server -->|"mounts route"| node_authroute
node_server -->|"mounts route"| node_holdingroute
node_server -->|"mounts route"| node_walletroute
node_server -->|"mounts route"| node_priceroute
node_server -->|"mounts route"| node_extractroute
node_server -->|"installs auth middleware"| node_authmw
node_server -->|"connects"| node_mongodb
node_authroute -->|"uses"| node_authmw
node_authmw -->|"finds or creates user"| node_user_model
node_holdingroute -->|"reads and writes"| node_holdingmodel
node_walletroute -->|"reads and writes"| node_walletmodel
node_walletroute -->|"queries holdings"| node_holdingmodel
node_priceroute -->|"gets quotes"| node_pricesvc
node_priceroute -->|"reads holdings"| node_holdingmodel
node_priceroute -->|"reads overrides"| node_priceoverride
node_extractroute -->|"authenticates"| node_authmw
node_extractroute -->|"runs extraction"| node_pipeline
node_pipeline -->|"tries vision extraction"| node_vision
node_pipeline -->|"runs OCR"| node_ocr
node_pipeline -->|"tries fallback"| node_groq
node_pipeline -->|"tries fallback"| node_openrouter
node_pipeline -->|"validates results"| node_extractvalidate
node_pricesvc -->|"reads and updates"| node_pricecache
node_pricesvc -->|"reads overrides"| node_priceoverride
node_server -->|"starts price cron"| node_pricesvc
node_holdingmodel -.->|"persists data"| node_mongodb
node_walletmodel -.->|"persists data"| node_mongodb
node_user_model -.->|"persists data"| node_mongodb
node_pricecache -.->|"persists cache"| node_mongodb

click node_app "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/App.jsx"
click node_authctx "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/context/AuthContext.jsx"
click node_walletctx "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/context/WalletContext.jsx"
click node_api_client "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/api/axiosInstance.js"
click node_dashboard "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/pages/DashboardPage.jsx"
click node_analytics "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/pages/AnalyticsPage.jsx"
click node_walletpages "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/pages/WalletsPage.jsx"
click node_walletdetail "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/pages/WalletDetailPage.jsx"
click node_holdings_ui "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/components/HoldingsTable.jsx"
click node_extract_ui "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/components/ExtractionReviewModal.jsx"
click node_server "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/index.js"
click node_authmw "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/middleware/auth.js"
click node_authroute "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/routes/auth.js"
click node_holdingroute "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/routes/holdings.js"
click node_walletroute "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/routes/wallets.js"
click node_priceroute "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/routes/prices.js"
click node_extractroute "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/routes/extract.js"
click node_pipeline "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/extractionPipeline.js"
click node_extractvalidate "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/validateExtraction.js"
click node_vision "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/geminiExtract.js"
click node_ocr "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/ocrExtract.js"
click node_groq "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/groqExtract.js"
click node_openrouter "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/openrouterExtract.js"
click node_pricesvc "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/priceService.js"
click node_holdingmodel "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/models/Holding.js"
click node_walletmodel "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/models/Wallet.js"
click node_user_model "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/models/User.js"
click node_pricecache "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/models/PriceCache.js"
click node_priceoverride "https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/models/PriceOverride.js"

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_app,node_authctx,node_walletctx,node_api_client,node_dashboard,node_analytics,node_walletpages,node_walletdetail,node_holdings_ui,node_extract_ui,node_user toneBlue
class node_server,node_authmw,node_authroute,node_user_model,node_mongodb toneAmber
class node_holdingroute,node_walletroute,node_holdingmodel,node_walletmodel toneMint
class node_priceroute,node_extractroute,node_pipeline,node_extractvalidate,node_vision,node_ocr,node_groq,node_openrouter,node_pricesvc,node_pricecache,node_priceoverride toneRose
```

## Components

### Portfolio client

- [App coordinator](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Authentication state](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/context/AuthContext.jsx): `client/src/context/AuthContext.jsx`
- [Wallet state](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/context/WalletContext.jsx): `client/src/context/WalletContext.jsx`
- [API client](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/api/axiosInstance.js): `client/src/api/axiosInstance.js`
- [Dashboard](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/pages/DashboardPage.jsx): `client/src/pages/DashboardPage.jsx`
- [Portfolio analytics](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/pages/AnalyticsPage.jsx): `client/src/pages/AnalyticsPage.jsx`
- [Wallet views](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/pages/WalletsPage.jsx): `client/src/pages/WalletsPage.jsx`
- [Wallet detail](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/pages/WalletDetailPage.jsx): `client/src/pages/WalletDetailPage.jsx`
- [Holdings table](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/components/HoldingsTable.jsx): `client/src/components/HoldingsTable.jsx`
- [Extraction review](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/client/src/components/ExtractionReviewModal.jsx): `client/src/components/ExtractionReviewModal.jsx`

### API and identity

- [Express API](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/index.js): `server/src/index.js`
- [Auth middleware](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/middleware/auth.js): `server/src/middleware/auth.js`
- [Auth routes](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/routes/auth.js): `server/src/routes/auth.js`
- [User store](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/models/User.js): `server/src/models/User.js`

### Portfolio data

- [Holdings routes](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/routes/holdings.js): `server/src/routes/holdings.js`
- [Wallet routes](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/routes/wallets.js): `server/src/routes/wallets.js`
- [Holdings store](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/models/Holding.js): `server/src/models/Holding.js`
- [Wallet store](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/models/Wallet.js): `server/src/models/Wallet.js`

### Pricing and extraction

- [Price routes](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/routes/prices.js): `server/src/routes/prices.js`
- [Extraction route](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/routes/extract.js): `server/src/routes/extract.js`
- [Extraction pipeline](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/extractionPipeline.js): `server/src/services/extraction/extractionPipeline.js`
- [Result validation](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/validateExtraction.js): `server/src/services/extraction/validateExtraction.js`
- [Gemini extraction](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/geminiExtract.js): `server/src/services/extraction/geminiExtract.js`
- [OCR extraction](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/ocrExtract.js): `server/src/services/extraction/ocrExtract.js`
- [Groq extraction](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/groqExtract.js): `server/src/services/extraction/groqExtract.js`
- [OpenRouter extraction](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/extraction/openrouterExtract.js): `server/src/services/extraction/openrouterExtract.js`
- [Price service](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/services/priceService.js): `server/src/services/priceService.js`
- [Price cache](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/models/PriceCache.js): `server/src/models/PriceCache.js`
- [Price overrides](https://github.com/stephin-mathew/mern-portfolio-tracker/blob/main/server/src/models/PriceOverride.js): `server/src/models/PriceOverride.js`

### Other components

- **Portfolio user**
- **MongoDB**

## Connections

- Portfolio user → App coordinator: uses (evidence: `client/src/App.jsx`)
- App coordinator → Dashboard: routes to (evidence: `client/src/App.jsx`)
- App coordinator → Portfolio analytics: routes to (evidence: `client/src/App.jsx`)
- App coordinator → Wallet views: routes to (evidence: `client/src/App.jsx`)
- App coordinator → Wallet detail: routes to (evidence: `client/src/App.jsx`)
- App coordinator → API client: fetches holdings and prices (evidence: `client/src/App.jsx`)
- App coordinator → Wallet state: orchestrates wallet fetch (evidence: `client/src/context/WalletContext.jsx`)
- Authentication state → API client: provides auth token (evidence: `client/src/context/AuthContext.jsx`)
- Wallet state → API client: fetches wallets (evidence: `client/src/context/WalletContext.jsx`)
- Dashboard → Holdings table: renders (evidence: `client/src/pages/DashboardPage.jsx`)
- Wallet detail → Holdings table: renders (evidence: `client/src/pages/WalletDetailPage.jsx`)
- Extraction review → API client: fetches review prices (evidence: `client/src/components/ExtractionReviewModal.jsx`)
- Express API → Auth routes: mounts route (evidence: `server/src/index.js`)
- Express API → Holdings routes: mounts route (evidence: `server/src/index.js`)
- Express API → Wallet routes: mounts route (evidence: `server/src/index.js`)
- Express API → Price routes: mounts route (evidence: `server/src/index.js`)
- Express API → Extraction route: mounts route (evidence: `server/src/index.js`)
- Express API → Auth middleware: installs auth middleware (evidence: `server/src/index.js`)
- Express API → MongoDB: connects (evidence: `server/src/index.js`)
- Auth routes → Auth middleware: uses (evidence: `server/src/routes/auth.js`)
- Auth middleware → User store: finds or creates user (evidence: `server/src/middleware/auth.js`)
- Holdings routes → Holdings store: reads and writes (evidence: `server/src/routes/holdings.js`)
- Wallet routes → Wallet store: reads and writes (evidence: `server/src/routes/wallets.js`)
- Wallet routes → Holdings store: queries holdings (evidence: `server/src/routes/wallets.js`)
- Price routes → Price service: gets quotes (evidence: `server/src/routes/prices.js`)
- Price routes → Holdings store: reads holdings (evidence: `server/src/routes/prices.js`)
- Price routes → Price overrides: reads overrides (evidence: `server/src/routes/prices.js`)
- Extraction route → Auth middleware: authenticates (evidence: `server/src/routes/extract.js`)
- Extraction route → Extraction pipeline: runs extraction (evidence: `server/src/routes/extract.js`)
- Extraction pipeline → Gemini extraction: tries vision extraction (evidence: `server/src/services/extraction/extractionPipeline.js`)
- Extraction pipeline → OCR extraction: runs OCR (evidence: `server/src/services/extraction/extractionPipeline.js`)
- Extraction pipeline → Groq extraction: tries fallback (evidence: `server/src/services/extraction/extractionPipeline.js`)
- Extraction pipeline → OpenRouter extraction: tries fallback (evidence: `server/src/services/extraction/extractionPipeline.js`)
- Extraction pipeline → Result validation: validates results (evidence: `server/src/services/extraction/extractionPipeline.js`)
- Price service → Price cache: reads and updates (evidence: `server/src/services/priceService.js`)
- Price service → Price overrides: reads overrides (evidence: `server/src/services/priceService.js`)
- Express API → Price service: starts price cron (evidence: `server/src/index.js`)
- Holdings store → MongoDB: persists data
- Wallet store → MongoDB: persists data
- User store → MongoDB: persists data
- Price cache → MongoDB: persists cache
