# username67-afk/ai-investment-terminal architecture

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

- Interactive diagram: https://gitdiagram.com/username67-afk/ai-investment-terminal
- Repository: https://github.com/username67-afk/ai-investment-terminal

## Overview

This is a terminal-based Indian-stock research tool. Users search mapped companies, then the CLI gathers market data and presents technical returns, risk metrics, fundamentals, and headline sentiment; separate menu flows compare stocks and manage a portfolio and watchlist. The graph preserves those documented capabilities, including signals and ASCII charts. The source excerpts show the main CLI calls and data-service relationships; signals and charts are documented as not yet integrated into the main analysis flow.

Main entry points: [`app.py`](https://github.com/username67-afk/ai-investment-terminal/blob/main/app.py) (CLI menus), [`services/market_data.py`](https://github.com/username67-afk/ai-investment-terminal/blob/main/services/market_data.py) (Market data), [`utils/storage.py`](https://github.com/username67-afk/ai-investment-terminal/blob/main/utils/storage.py) (Cache and user storage), [`config/settings.py`](https://github.com/username67-afk/ai-investment-terminal/blob/main/config/settings.py) (Application settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Terminal workflows"]
  node_app["CLI menus<br/>[app.py]"]
end

subgraph group_research["Research analysis"]
  node_technical["Technical indicators<br/>[technical.py]"]
  node_risk["Risk metrics<br/>[risk.py]"]
  node_sentiment["News sentiment<br/>[sentiment_model.py]"]
  node_signals["Signal engine<br/>[signals.py]"]
  node_portfolio_analysis["Portfolio analysis<br/>[portfolio.py]"]
  node_charts["ASCII charts<br/>[terminal_charts.py]"]
end

subgraph group_services["Data services"]
  node_search["Company search<br/>[company_search.py]"]
  node_mapping["Company mapping"]
  node_market["Market data<br/>[market_data.py]"]
  node_news["News retrieval<br/>[news_data.py]"]
  node_settings["Application settings<br/>[settings.py]"]
end

subgraph group_persistence["Local persistence"]
  node_storage["Cache and user storage<br/>[storage.py]"]
  node_cache[("Response cache")]
  node_userdata[("Portfolio and watchlist<br/>[user_data.json]")]
end

node_user(("Researcher"))
node_yahoo["Yahoo Finance"]
node_google["Google News RSS"]

node_user -->|"selects workflow"| node_app
node_app -->|"searches companies"| node_search
node_search -->|"reads mapping"| node_mapping
node_app -->|"requests market data"| node_market
node_market -->|"fetches prices"| node_yahoo
node_app -->|"computes indicators"| node_technical
node_app -->|"computes risk"| node_risk
node_app -->|"requests headlines"| node_news
node_news -->|"queries RSS"| node_google
node_app -->|"scores headlines"| node_sentiment
node_app -->|"summarizes holdings"| node_portfolio_analysis
node_portfolio_analysis -->|"gets quotes and history"| node_market
node_app -->|"reads and updates lists"| node_storage
node_storage -->|"reads and writes"| node_userdata
node_market -->|"uses cache"| node_storage
node_storage -->|"reads and writes"| node_cache
node_search -->|"gets mapping path"| node_settings
node_market -->|"gets defaults"| node_settings
node_news -->|"gets feed settings"| node_settings
node_risk -->|"gets risk-free rate"| node_settings
node_app -.->|"planned integration"| node_signals
node_app -.->|"planned integration"| node_charts

click node_app "https://github.com/username67-afk/ai-investment-terminal/blob/main/app.py"
click node_search "https://github.com/username67-afk/ai-investment-terminal/blob/main/services/company_search.py"
click node_mapping "https://github.com/username67-afk/ai-investment-terminal/blob/main/data/company_mapping.csv"
click node_market "https://github.com/username67-afk/ai-investment-terminal/blob/main/services/market_data.py"
click node_news "https://github.com/username67-afk/ai-investment-terminal/blob/main/services/news_data.py"
click node_technical "https://github.com/username67-afk/ai-investment-terminal/blob/main/analysis/technical.py"
click node_risk "https://github.com/username67-afk/ai-investment-terminal/blob/main/analysis/risk.py"
click node_sentiment "https://github.com/username67-afk/ai-investment-terminal/blob/main/models/sentiment_model.py"
click node_signals "https://github.com/username67-afk/ai-investment-terminal/blob/main/analysis/signals.py"
click node_portfolio_analysis "https://github.com/username67-afk/ai-investment-terminal/blob/main/analysis/portfolio.py"
click node_charts "https://github.com/username67-afk/ai-investment-terminal/blob/main/ui/terminal_charts.py"
click node_storage "https://github.com/username67-afk/ai-investment-terminal/blob/main/utils/storage.py"
click node_cache "https://github.com/username67-afk/ai-investment-terminal/tree/main/data/cache"
click node_userdata "https://github.com/username67-afk/ai-investment-terminal/blob/main/data/user_data.json"
click node_settings "https://github.com/username67-afk/ai-investment-terminal/blob/main/config/settings.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_app toneBlue
class node_technical,node_risk,node_sentiment,node_signals,node_portfolio_analysis,node_charts toneAmber
class node_search,node_mapping,node_market,node_news,node_settings toneMint
class node_storage,node_cache,node_userdata toneRose
class node_user,node_yahoo,node_google toneIndigo
```

## Components

### Terminal workflows

- [CLI menus](https://github.com/username67-afk/ai-investment-terminal/blob/main/app.py): `app.py`

### Research analysis

- [Technical indicators](https://github.com/username67-afk/ai-investment-terminal/blob/main/analysis/technical.py): `analysis/technical.py`
- [Risk metrics](https://github.com/username67-afk/ai-investment-terminal/blob/main/analysis/risk.py): `analysis/risk.py`
- [News sentiment](https://github.com/username67-afk/ai-investment-terminal/blob/main/models/sentiment_model.py): `models/sentiment_model.py`
- [Signal engine](https://github.com/username67-afk/ai-investment-terminal/blob/main/analysis/signals.py): `analysis/signals.py`
- [Portfolio analysis](https://github.com/username67-afk/ai-investment-terminal/blob/main/analysis/portfolio.py): `analysis/portfolio.py`
- [ASCII charts](https://github.com/username67-afk/ai-investment-terminal/blob/main/ui/terminal_charts.py): `ui/terminal_charts.py`

### Data services

- [Company search](https://github.com/username67-afk/ai-investment-terminal/blob/main/services/company_search.py): `services/company_search.py`
- [Company mapping](https://github.com/username67-afk/ai-investment-terminal/blob/main/data/company_mapping.csv): `data/company_mapping.csv`
- [Market data](https://github.com/username67-afk/ai-investment-terminal/blob/main/services/market_data.py): `services/market_data.py`
- [News retrieval](https://github.com/username67-afk/ai-investment-terminal/blob/main/services/news_data.py): `services/news_data.py`
- [Application settings](https://github.com/username67-afk/ai-investment-terminal/blob/main/config/settings.py): `config/settings.py`

### Local persistence

- [Cache and user storage](https://github.com/username67-afk/ai-investment-terminal/blob/main/utils/storage.py): `utils/storage.py`
- [Response cache](https://github.com/username67-afk/ai-investment-terminal/tree/main/data/cache): `data/cache`
- [Portfolio and watchlist](https://github.com/username67-afk/ai-investment-terminal/blob/main/data/user_data.json): `data/user_data.json`

### Other components

- **Researcher**
- **Yahoo Finance**
- **Google News RSS**

## Connections

- Researcher → CLI menus: selects workflow (evidence: `README.md`)
- CLI menus → Company search: searches companies (evidence: `app.py`)
- Company search → Company mapping: reads mapping (evidence: `services/company_search.py`)
- CLI menus → Market data: requests market data (evidence: `app.py`)
- Market data → Yahoo Finance: fetches prices (evidence: `services/market_data.py`)
- CLI menus → Technical indicators: computes indicators (evidence: `app.py`)
- CLI menus → Risk metrics: computes risk (evidence: `app.py`)
- CLI menus → News retrieval: requests headlines (evidence: `app.py`)
- News retrieval → Google News RSS: queries RSS (evidence: `services/news_data.py`)
- CLI menus → News sentiment: scores headlines (evidence: `app.py`)
- CLI menus → Portfolio analysis: summarizes holdings (evidence: `app.py`)
- Portfolio analysis → Market data: gets quotes and history (evidence: `analysis/portfolio.py`)
- CLI menus → Cache and user storage: reads and updates lists (evidence: `app.py`)
- Cache and user storage → Portfolio and watchlist: reads and writes (evidence: `utils/storage.py`)
- Market data → Cache and user storage: uses cache (evidence: `services/market_data.py`)
- Cache and user storage → Response cache: reads and writes (evidence: `utils/storage.py`)
- Company search → Application settings: gets mapping path (evidence: `services/company_search.py`)
- Market data → Application settings: gets defaults (evidence: `services/market_data.py`)
- News retrieval → Application settings: gets feed settings (evidence: `services/news_data.py`)
- Risk metrics → Application settings: gets risk-free rate (evidence: `analysis/risk.py`)
- CLI menus → Signal engine: planned integration (evidence: `README.md`)
- CLI menus → ASCII charts: planned integration (evidence: `README.md`)
