# jeremiahogingo/crypto-portfolio-tracker architecture

> Architecture diagram of the GitHub repository jeremiahogingo/crypto-portfolio-tracker, 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/jeremiahogingo/crypto-portfolio-tracker
- Repository: https://github.com/jeremiahogingo/crypto-portfolio-tracker

## Overview

Crypto Portfolio Tracker is a Next.js portfolio-management and market-information app, not a trading or custodial system. Users sign in and onboard, record holdings and ledger transactions, then review priced positions, analytics, markets, news, watchlists, and stored alert configurations. The README documents authenticated Server Actions and a decimal ledger/database layer; sampled hooks and route handlers show the public market/news data path. Some feature implementations were not sampled, so their connections are included only where the README explicitly describes them.

Main entry points: [`src/lib/actions`](https://github.com/jeremiahogingo/crypto-portfolio-tracker/tree/main/src/lib/actions) (Portfolio actions), [`src/lib/api/client.ts`](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/api/client.ts) (Browser API client), [`src/app`](https://github.com/jeremiahogingo/crypto-portfolio-tracker/tree/main/src/app) (App pages), [`src/app/(dashboard)/page.tsx`](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/app/(dashboard)/page.tsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_app_routes["App pages"]
end

subgraph group_portfolio["Portfolio"]
  node_portfolio_ui["Portfolio views"]
  node_dashboard_ui["Dashboard<br/>[page.tsx]"]
  node_portfolio_actions["Portfolio actions"]
  node_portfolio_queries["Portfolio queries<br/>[queries.ts]"]
  node_ledger["Ledger and recompute<br/>[ledger.ts]"]
  node_analytics["Analytics calculations<br/>[calc.ts]"]
  node_priced_holdings["Priced holdings"]
end

subgraph group_market["Market intelligence"]
  node_market_hook["Market query hook<br/>[useMarkets.ts]"]
  node_api_client["Browser API client<br/>[client.ts]"]
  node_market_routes["Market handlers"]
  node_coingecko["CoinGecko adapter<br/>[coingecko.ts]"]
  node_normalizer["Market normalizer<br/>[normalize.ts]"]
  node_news_hook["News query hook<br/>[useNews.ts]"]
  node_news_route["News handler<br/>[route.ts]"]
  node_news_adapter["RSS aggregation<br/>[news.ts]"]
end

subgraph group_user_features["User features"]
  node_watchlist["Watchlist<br/>[WatchlistView.tsx]"]
  node_alerts["Price alerts<br/>[AlertsView.tsx]"]
end

subgraph group_infra["Identity and storage"]
  node_auth["Session verification"]
  node_actions["User Server Actions"]
  node_schema["Database schema<br/>[schema.ts]"]
end

node_user(("User"))
node_market_provider{{"CoinGecko"}}
node_news_sources{{"RSS and Atom feeds"}}
node_supabase{{"Supabase Auth"}}
node_postgres[("PostgreSQL")]

node_user -->|"uses"| node_app_routes
node_app_routes -->|"renders"| node_portfolio_ui
node_app_routes -->|"renders"| node_dashboard_ui
node_dashboard_ui -->|"loads holdings"| node_portfolio_queries
node_dashboard_ui -->|"calculates summary"| node_analytics
node_portfolio_ui -.->|"mutates portfolio"| node_portfolio_actions
node_portfolio_actions -->|"verifies session"| node_auth
node_portfolio_actions -.->|"replays ledger"| node_ledger
node_portfolio_actions -.->|"persists changes"| node_postgres
node_portfolio_queries -.->|"reads positions"| node_postgres
node_ledger -.->|"uses transaction model"| node_schema
node_schema -->|"defines tables"| node_postgres
node_priced_holdings -->|"requests quotes"| node_market_hook
node_market_hook -->|"fetches JSON"| node_api_client
node_api_client -->|"calls endpoint"| node_market_routes
node_market_routes -->|"fetches market data"| node_coingecko
node_market_routes -->|"normalizes coins"| node_normalizer
node_coingecko -->|"requests quotes"| node_market_provider
node_news_hook -->|"fetches JSON"| node_api_client
node_api_client -->|"calls endpoint"| node_news_route
node_news_route -->|"gets articles"| node_news_adapter
node_news_adapter -.->|"aggregates feeds"| node_news_sources
node_watchlist -.->|"manages assets"| node_actions
node_alerts -.->|"stores configs"| node_actions
node_auth -.->|"checks session"| node_supabase
node_actions -.->|"writes user data"| node_postgres

click node_app_routes "https://github.com/jeremiahogingo/crypto-portfolio-tracker/tree/main/src/app"
click node_portfolio_ui "https://github.com/jeremiahogingo/crypto-portfolio-tracker/tree/main/src/components/portfolio"
click node_dashboard_ui "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/app/(dashboard)/page.tsx"
click node_portfolio_actions "https://github.com/jeremiahogingo/crypto-portfolio-tracker/tree/main/src/lib/actions"
click node_portfolio_queries "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/portfolio/queries.ts"
click node_ledger "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/portfolio/ledger.ts"
click node_analytics "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/analytics/calc.ts"
click node_priced_holdings "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/hooks/useHoldingsWithPrices.ts"
click node_market_hook "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/hooks/useMarkets.ts"
click node_api_client "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/api/client.ts"
click node_market_routes "https://github.com/jeremiahogingo/crypto-portfolio-tracker/tree/main/src/app/api/crypto"
click node_coingecko "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/api/coingecko.ts"
click node_normalizer "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/api/normalize.ts"
click node_news_hook "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/hooks/useNews.ts"
click node_news_route "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/app/api/crypto/news/route.ts"
click node_news_adapter "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/api/news.ts"
click node_watchlist "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/components/watchlist/WatchlistView.tsx"
click node_alerts "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/components/alerts/AlertsView.tsx"
click node_auth "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/auth/get-current-user.ts"
click node_actions "https://github.com/jeremiahogingo/crypto-portfolio-tracker/tree/main/src/lib/actions"
click node_schema "https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/db/schema.ts"

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_routes,node_user toneBlue
class node_portfolio_ui,node_dashboard_ui,node_portfolio_actions,node_portfolio_queries,node_ledger,node_analytics,node_priced_holdings,node_postgres toneAmber
class node_market_hook,node_api_client,node_market_routes,node_coingecko,node_normalizer,node_news_hook,node_news_route,node_news_adapter toneMint
class node_watchlist,node_alerts toneRose
class node_auth,node_actions,node_schema,node_market_provider,node_news_sources,node_supabase toneIndigo
```

## Components

### Application

- [App pages](https://github.com/jeremiahogingo/crypto-portfolio-tracker/tree/main/src/app): `src/app`

### Portfolio

- [Portfolio views](https://github.com/jeremiahogingo/crypto-portfolio-tracker/tree/main/src/components/portfolio): `src/components/portfolio`
- [Dashboard](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/app/(dashboard)/page.tsx): `src/app/(dashboard)/page.tsx`
- [Portfolio actions](https://github.com/jeremiahogingo/crypto-portfolio-tracker/tree/main/src/lib/actions): `src/lib/actions`
- [Portfolio queries](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/portfolio/queries.ts): `src/lib/portfolio/queries.ts`
- [Ledger and recompute](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/portfolio/ledger.ts): `src/lib/portfolio/ledger.ts`
- [Analytics calculations](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/analytics/calc.ts): `src/lib/analytics/calc.ts`
- [Priced holdings](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/hooks/useHoldingsWithPrices.ts): `src/hooks/useHoldingsWithPrices.ts`

### Market intelligence

- [Market query hook](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/hooks/useMarkets.ts): `src/hooks/useMarkets.ts`
- [Browser API client](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/api/client.ts): `src/lib/api/client.ts`
- [Market handlers](https://github.com/jeremiahogingo/crypto-portfolio-tracker/tree/main/src/app/api/crypto): `src/app/api/crypto`
- [CoinGecko adapter](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/api/coingecko.ts): `src/lib/api/coingecko.ts`
- [Market normalizer](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/api/normalize.ts): `src/lib/api/normalize.ts`
- [News query hook](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/hooks/useNews.ts): `src/hooks/useNews.ts`
- [News handler](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/app/api/crypto/news/route.ts): `src/app/api/crypto/news/route.ts`
- [RSS aggregation](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/api/news.ts): `src/lib/api/news.ts`

### User features

- [Watchlist](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/components/watchlist/WatchlistView.tsx): `src/components/watchlist/WatchlistView.tsx`
- [Price alerts](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/components/alerts/AlertsView.tsx): `src/components/alerts/AlertsView.tsx`

### Identity and storage

- [Session verification](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/lib/auth/get-current-user.ts): `src/lib/auth/get-current-user.ts`
- [User Server Actions](https://github.com/jeremiahogingo/crypto-portfolio-tracker/tree/main/src/lib/actions): `src/lib/actions`
- [Database schema](https://github.com/jeremiahogingo/crypto-portfolio-tracker/blob/main/src/db/schema.ts): `src/db/schema.ts`

### Other components

- **User**
- **CoinGecko**
- **RSS and Atom feeds**
- **Supabase Auth**
- **PostgreSQL**

## Connections

- User → App pages: uses
- App pages → Portfolio views: renders
- App pages → Dashboard: renders (evidence: `src/app/(dashboard)/page.tsx`)
- Dashboard → Portfolio queries: loads holdings (evidence: `src/app/(dashboard)/page.tsx`)
- Dashboard → Analytics calculations: calculates summary (evidence: `src/app/(dashboard)/page.tsx`)
- Portfolio views → Portfolio actions: mutates portfolio
- Portfolio actions → Session verification: verifies session
- Portfolio actions → Ledger and recompute: replays ledger
- Portfolio actions → PostgreSQL: persists changes
- Portfolio queries → PostgreSQL: reads positions
- Ledger and recompute → Database schema: uses transaction model
- Database schema → PostgreSQL: defines tables (evidence: `src/db/schema.ts`)
- Priced holdings → Market query hook: requests quotes (evidence: `src/hooks/useHoldingsWithPrices.ts`)
- Market query hook → Browser API client: fetches JSON (evidence: `src/hooks/useMarkets.ts`)
- Browser API client → Market handlers: calls endpoint
- Market handlers → CoinGecko adapter: fetches market data (evidence: `src/app/api/crypto/markets/route.ts`)
- Market handlers → Market normalizer: normalizes coins (evidence: `src/app/api/crypto/markets/route.ts`)
- CoinGecko adapter → CoinGecko: requests quotes (evidence: `src/lib/api/coingecko.ts`)
- News query hook → Browser API client: fetches JSON (evidence: `src/hooks/useNews.ts`)
- Browser API client → News handler: calls endpoint
- News handler → RSS aggregation: gets articles (evidence: `src/app/api/crypto/news/route.ts`)
- RSS aggregation → RSS and Atom feeds: aggregates feeds
- Watchlist → User Server Actions: manages assets
- Price alerts → User Server Actions: stores configs
- Session verification → Supabase Auth: checks session
- User Server Actions → PostgreSQL: writes user data
