# jfarid27/hyperfin-terminal architecture

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

- Interactive diagram: https://gitdiagram.com/jfarid27/hyperfin-terminal
- Repository: https://github.com/jfarid27/hyperfin-terminal

## Overview

Hyperfin is an interactive financial-markets CLI. Users enter a domain menu, request market or economic data, and view results in the terminal; the README also documents running command scripts and configuring API keys. The graph preserves the documented asset, news, options, and prediction-market branches. Detailed call wiring is sampled only for the application entry and stock and Yahoo Finance services, so other menu-to-service connections are shown at subsystem level rather than as inferred internal pipelines.

Main entry points: [`src/cli/index.ts`](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/index.ts) (Main menu), [`src/services/MassiveService/index.ts`](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/MassiveService/index.ts) (Massive service), [`src/cli/StocksMenu/index.ts`](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/StocksMenu/index.ts) (Stocks menu), [`src/cli/StocksMenu/actions/alphavantage.ts`](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/StocksMenu/actions/alphavantage.ts) (Stock actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["CLI runtime"]
  node_entry["Program entry<br/>[index.ts]"]
  node_main["Main menu<br/>[index.ts]"]
end

subgraph group_markets["Market menus"]
  node_stocks["Stocks menu<br/>[index.ts]"]
  node_stockactions["Stock actions<br/>[alphavantage.ts]"]
  node_options["Options menu<br/>[index.ts]"]
  node_bonds["Bonds menu<br/>[index.ts]"]
  node_crypto["Crypto menu<br/>[index.ts]"]
  node_government["Government menu<br/>[index.ts]"]
  node_news["News menu<br/>[index.ts]"]
  node_predictions["Prediction menus<br/>[index.ts]"]
end

subgraph group_data["Data services"]
  node_stocksservices["Stock providers<br/>[index.ts]"]
  node_massive["Massive service<br/>[index.ts]"]
  node_optionsservice["Yahoo options"]
  node_bondsservice["Yahoo bonds"]
  node_cryptoservice["Crypto services<br/>[index.ts]"]
  node_governmentservice["Government service<br/>[index.ts]"]
  node_redditservice["Reddit service<br/>[index.ts]"]
  node_kalshi["Kalshi service<br/>[index.ts]"]
  node_polymarket["Polymarket service<br/>[index.ts]"]
end

subgraph group_shared["Shared services"]
  node_state["Terminal state"]
  node_fetch["Fetch service<br/>[FetchService.ts]"]
  node_config["Configuration<br/>[ConfigService.ts]"]
end

subgraph group_automation["Automation"]
  node_script["Script execution<br/>[scripts.ts]"]
end

node_user(("CLI user"))
node_yahoo{{"Yahoo Finance"}}
node_alphavantage{{"Alpha Vantage"}}
node_massiveapi{{"Massive API"}}
node_fred{{"FRED API"}}
node_coingecko{{"CoinGecko API"}}
node_reddit{{"Reddit"}}
node_kalshiapi{{"Kalshi API"}}
node_polymarketapi{{"Polymarket API"}}
node_terminal(("Terminal output"))

node_user -->|"starts"| node_entry
node_entry -->|"starts"| node_main
node_main -->|"initializes"| node_state
node_main -->|"dispatches"| node_stocks
node_main -->|"dispatches"| node_options
node_main -->|"dispatches"| node_bonds
node_main -->|"dispatches"| node_crypto
node_main -->|"dispatches"| node_government
node_main -->|"dispatches"| node_news
node_main -->|"dispatches"| node_predictions
node_main -->|"dispatches"| node_script
node_stocks -->|"handles"| node_stockactions
node_stockactions -->|"queries"| node_stocksservices
node_stockactions -->|"queries"| node_massive
node_stocksservices -->|"fetches via"| node_fetch
node_massive -->|"fetches via"| node_fetch
node_stocksservices -->|"reads key"| node_config
node_massive -->|"reads key"| node_config
node_fetch -->|"requests"| node_alphavantage
node_massive -->|"requests"| node_massiveapi
node_optionsservice -->|"requests"| node_yahoo
node_bondsservice -->|"requests"| node_yahoo
node_governmentservice -.->|"requests"| node_fred
node_cryptoservice -.->|"requests"| node_coingecko
node_redditservice -.->|"requests"| node_reddit
node_kalshi -.->|"requests"| node_kalshiapi
node_polymarket -.->|"requests"| node_polymarketapi
node_stocks -->|"displays"| node_terminal
node_options -->|"displays"| node_terminal
node_bonds -->|"displays"| node_terminal
node_crypto -->|"displays"| node_terminal
node_government -->|"displays"| node_terminal
node_news -->|"displays"| node_terminal
node_predictions -->|"displays"| node_terminal
node_user -->|"enters commands"| node_main
node_script -->|"executes commands"| node_main

click node_entry "https://github.com/jfarid27/hyperfin-terminal/blob/development/index.ts"
click node_main "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/index.ts"
click node_state "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/services/TerminalUserState.ts"
click node_stocks "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/StocksMenu/index.ts"
click node_stockactions "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/StocksMenu/actions/alphavantage.ts"
click node_options "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/OptionsMenu/index.ts"
click node_bonds "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/BondsMenu/index.ts"
click node_crypto "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/CryptoMenu/index.ts"
click node_government "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/GovernmentMenu/index.ts"
click node_news "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/NewsMenu/index.ts"
click node_predictions "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/PredictionMarketMenu/index.ts"
click node_stocksservices "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/AlphaVantageService/index.ts"
click node_massive "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/MassiveService/index.ts"
click node_optionsservice "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/OptionsService/YahooFinanceOptionsService.ts"
click node_bondsservice "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/BondsService/YahooFinanceBondsService.ts"
click node_cryptoservice "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/CryptoService/index.ts"
click node_governmentservice "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/GovernmentService/index.ts"
click node_redditservice "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/RedditService/index.ts"
click node_kalshi "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/KalshiService/index.ts"
click node_polymarket "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/PolymarketService/index.ts"
click node_fetch "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/services/FetchService.ts"
click node_config "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/services/ConfigService.ts"
click node_script "https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/utils/scripts.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_entry,node_main,node_user toneBlue
class node_stocks,node_stockactions,node_options,node_bonds,node_crypto,node_government,node_news,node_predictions toneAmber
class node_stocksservices,node_massive,node_optionsservice,node_bondsservice,node_cryptoservice,node_governmentservice,node_redditservice,node_kalshi,node_polymarket,node_massiveapi,node_fred,node_coingecko,node_kalshiapi,node_polymarketapi toneMint
class node_state,node_fetch,node_config toneRose
class node_script,node_yahoo,node_alphavantage,node_reddit,node_terminal toneIndigo
```

## Components

### CLI runtime

- [Program entry](https://github.com/jfarid27/hyperfin-terminal/blob/development/index.ts): `index.ts`
- [Main menu](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/index.ts): `src/cli/index.ts`

### Market menus

- [Stocks menu](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/StocksMenu/index.ts): `src/cli/StocksMenu/index.ts`
- [Stock actions](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/StocksMenu/actions/alphavantage.ts): `src/cli/StocksMenu/actions/alphavantage.ts`
- [Options menu](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/OptionsMenu/index.ts): `src/cli/OptionsMenu/index.ts`
- [Bonds menu](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/BondsMenu/index.ts): `src/cli/BondsMenu/index.ts`
- [Crypto menu](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/CryptoMenu/index.ts): `src/cli/CryptoMenu/index.ts`
- [Government menu](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/GovernmentMenu/index.ts): `src/cli/GovernmentMenu/index.ts`
- [News menu](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/NewsMenu/index.ts): `src/cli/NewsMenu/index.ts`
- [Prediction menus](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/PredictionMarketMenu/index.ts): `src/cli/PredictionMarketMenu/index.ts`

### Data services

- [Stock providers](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/AlphaVantageService/index.ts): `src/services/AlphaVantageService/index.ts`
- [Massive service](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/MassiveService/index.ts): `src/services/MassiveService/index.ts`
- [Yahoo options](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/OptionsService/YahooFinanceOptionsService.ts): `src/services/OptionsService/YahooFinanceOptionsService.ts`
- [Yahoo bonds](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/BondsService/YahooFinanceBondsService.ts): `src/services/BondsService/YahooFinanceBondsService.ts`
- [Crypto services](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/CryptoService/index.ts): `src/services/CryptoService/index.ts`
- [Government service](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/GovernmentService/index.ts): `src/services/GovernmentService/index.ts`
- [Reddit service](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/RedditService/index.ts): `src/services/RedditService/index.ts`
- [Kalshi service](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/KalshiService/index.ts): `src/services/KalshiService/index.ts`
- [Polymarket service](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/services/PolymarketService/index.ts): `src/services/PolymarketService/index.ts`

### Shared services

- [Terminal state](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/services/TerminalUserState.ts): `src/cli/services/TerminalUserState.ts`
- [Fetch service](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/services/FetchService.ts): `src/cli/services/FetchService.ts`
- [Configuration](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/services/ConfigService.ts): `src/cli/services/ConfigService.ts`

### Automation

- [Script execution](https://github.com/jfarid27/hyperfin-terminal/blob/development/src/cli/utils/scripts.ts): `src/cli/utils/scripts.ts`

### Other components

- **CLI user**
- **Yahoo Finance**
- **Alpha Vantage**
- **Massive API**
- **FRED API**
- **CoinGecko API**
- **Reddit**
- **Kalshi API**
- **Polymarket API**
- **Terminal output**

## Connections

- CLI user → Program entry: starts
- Program entry → Main menu: starts
- Main menu → Terminal state: initializes
- Main menu → Stocks menu: dispatches
- Main menu → Options menu: dispatches
- Main menu → Bonds menu: dispatches
- Main menu → Crypto menu: dispatches
- Main menu → Government menu: dispatches
- Main menu → News menu: dispatches
- Main menu → Prediction menus: dispatches
- Main menu → Script execution: dispatches
- Stocks menu → Stock actions: handles
- Stock actions → Stock providers: queries
- Stock actions → Massive service: queries
- Stock providers → Fetch service: fetches via
- Massive service → Fetch service: fetches via
- Stock providers → Configuration: reads key
- Massive service → Configuration: reads key
- Fetch service → Alpha Vantage: requests
- Massive service → Massive API: requests
- Yahoo options → Yahoo Finance: requests
- Yahoo bonds → Yahoo Finance: requests
- Government service → FRED API: requests
- Crypto services → CoinGecko API: requests
- Reddit service → Reddit: requests
- Kalshi service → Kalshi API: requests
- Polymarket service → Polymarket API: requests
- Stocks menu → Terminal output: displays
- Options menu → Terminal output: displays
- Bonds menu → Terminal output: displays
- Crypto menu → Terminal output: displays
- Government menu → Terminal output: displays
- News menu → Terminal output: displays
- Prediction menus → Terminal output: displays
- CLI user → Main menu: enters commands
- Script execution → Main menu: executes commands