# personalaiengines/artha-terminal architecture

> Architecture diagram of the GitHub repository personalaiengines/artha-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/personalaiengines/artha-terminal
- Repository: https://github.com/personalaiengines/artha-terminal

## Overview

ARTHA is a self-hosted Indian-markets research terminal. A user explores market, stock, F&O, portfolio, and AI-analysis views; the web client requests backend data and presents sourced results. The backend combines stored and live market data with deterministic analysis, while the AI analyst narrates tool-returned facts. The README documents live-feed fallback, read-only broker access, charting, risk engines, and scheduled ingestion. Some links below rely on README documentation or SOURCE INDEX references; unsampled implementations are represented only at supported subsystem paths.

Main entry points: [`api/server.py`](https://github.com/personalaiengines/artha-terminal/blob/master/api/server.py) (JSON and WS API), [`agent/orchestration.py`](https://github.com/personalaiengines/artha-terminal/blob/master/agent/orchestration.py) (AI orchestration), [`agent/tools.py`](https://github.com/personalaiengines/artha-terminal/blob/master/agent/tools.py) (Analyst tools), [`web/app/(portal)/dashboard/page.tsx`](https://github.com/personalaiengines/artha-terminal/blob/master/web/app/(portal)/dashboard/page.tsx) (Research pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_portal["Research pages<br/>[page.tsx]"]
  node_charts["Charts<br/>[kline-chart.tsx]"]
  node_webapi["Web API routes<br/>[route.ts]"]
end

subgraph group_api["API and orchestration"]
  node_backend["JSON and WS API<br/>[server.py]"]
  node_ws["Live socket<br/>[ws.py]"]
  node_agent["AI orchestration<br/>[orchestration.py]"]
  node_prompts["Grounding prompts<br/>[prompts.py]"]
  node_tools["Analyst tools<br/>[tools.py]"]
  node_llm["Provider routing<br/>[llm_client.py]"]
end

subgraph group_research["Research engines"]
  node_stock["Stock research<br/>[stock_data.py]"]
  node_fno["F&amp;O analysis<br/>[fno_analysis.py]"]
  node_levels["F&amp;O orchestration<br/>[fno_service.py]"]
  node_risk["Risk engines<br/>[red_flags.py]"]
  node_news["News and search<br/>[market_news.py]"]
end

subgraph group_marketdata["Market data"]
  node_portfolio["Broker portfolio<br/>[upstox.py]"]
  node_feeds["Market feeds<br/>[upstox_stream.py]"]
  node_fallback["Live fallback<br/>[last_good.py]"]
  node_ingestion["Scheduled ingestion<br/>[scheduler.py]"]
end

subgraph group_storage["Data foundation"]
  node_db[("SQLite store<br/>[__init__.py]")]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("Researcher"))

node_user -->|"explores"| node_portal
node_portal -->|"views charts"| node_charts
node_portal -.->|"requests data"| node_webapi
node_webapi -->|"calls API"| node_backend
node_backend -->|"routes analysis"| node_stock
node_backend -->|"routes F&amp;O"| node_levels
node_backend -->|"routes news"| node_news
node_backend -->|"runs analyst"| node_agent
node_backend -->|"serves sockets"| node_ws
node_ws -->|"streams ticks"| node_feeds
node_agent -->|"builds prompts"| node_prompts
node_agent -->|"requests completion"| node_llm
node_agent -->|"dispatches tools"| node_tools
node_tools -->|"reads snapshots"| node_stock
node_tools -->|"runs scans"| node_risk
node_tools -->|"searches sources"| node_news
node_levels -->|"analyzes chain"| node_fno
node_levels -->|"fetches options"| node_portfolio
node_backend -.->|"reads broker book"| node_portfolio
node_backend -->|"serves stale values"| node_fallback
node_ingestion -->|"records jobs"| node_db
node_ingestion -->|"loads settings"| node_config
node_backend -->|"reads market data"| node_db
node_feeds -.->|"supports fallback"| node_fallback
node_stock -->|"reads records"| node_db
node_llm -->|"loads providers"| node_config

click node_portal "https://github.com/personalaiengines/artha-terminal/blob/master/web/app/(portal)/dashboard/page.tsx"
click node_charts "https://github.com/personalaiengines/artha-terminal/blob/master/web/components/widgets/kline-chart.tsx"
click node_webapi "https://github.com/personalaiengines/artha-terminal/blob/master/web/app/api/ai/route.ts"
click node_backend "https://github.com/personalaiengines/artha-terminal/blob/master/api/server.py"
click node_ws "https://github.com/personalaiengines/artha-terminal/blob/master/api/ws.py"
click node_agent "https://github.com/personalaiengines/artha-terminal/blob/master/agent/orchestration.py"
click node_prompts "https://github.com/personalaiengines/artha-terminal/blob/master/agent/prompts.py"
click node_tools "https://github.com/personalaiengines/artha-terminal/blob/master/agent/tools.py"
click node_llm "https://github.com/personalaiengines/artha-terminal/blob/master/agent/llm_client.py"
click node_stock "https://github.com/personalaiengines/artha-terminal/blob/master/services/stock_data.py"
click node_fno "https://github.com/personalaiengines/artha-terminal/blob/master/services/fno_analysis.py"
click node_levels "https://github.com/personalaiengines/artha-terminal/blob/master/services/fno_service.py"
click node_risk "https://github.com/personalaiengines/artha-terminal/blob/master/engines/red_flags.py"
click node_news "https://github.com/personalaiengines/artha-terminal/blob/master/services/market_news.py"
click node_portfolio "https://github.com/personalaiengines/artha-terminal/blob/master/services/upstox.py"
click node_feeds "https://github.com/personalaiengines/artha-terminal/blob/master/services/upstox_stream.py"
click node_fallback "https://github.com/personalaiengines/artha-terminal/blob/master/services/last_good.py"
click node_ingestion "https://github.com/personalaiengines/artha-terminal/blob/master/ingestion/scheduler.py"
click node_db "https://github.com/personalaiengines/artha-terminal/blob/master/db/__init__.py"
click node_config "https://github.com/personalaiengines/artha-terminal/blob/master/config.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_portal,node_charts,node_webapi toneBlue
class node_backend,node_ws,node_agent,node_prompts,node_tools,node_llm toneAmber
class node_stock,node_fno,node_levels,node_risk,node_news toneMint
class node_portfolio,node_feeds,node_fallback,node_ingestion toneRose
class node_db,node_config,node_user toneIndigo
```

## Components

### Web experience

- [Research pages](https://github.com/personalaiengines/artha-terminal/blob/master/web/app/(portal)/dashboard/page.tsx): `web/app/(portal)/dashboard/page.tsx`
- [Charts](https://github.com/personalaiengines/artha-terminal/blob/master/web/components/widgets/kline-chart.tsx): `web/components/widgets/kline-chart.tsx`
- [Web API routes](https://github.com/personalaiengines/artha-terminal/blob/master/web/app/api/ai/route.ts): `web/app/api/ai/route.ts`

### API and orchestration

- [JSON and WS API](https://github.com/personalaiengines/artha-terminal/blob/master/api/server.py): `api/server.py`
- [Live socket](https://github.com/personalaiengines/artha-terminal/blob/master/api/ws.py): `api/ws.py`
- [AI orchestration](https://github.com/personalaiengines/artha-terminal/blob/master/agent/orchestration.py): `agent/orchestration.py`
- [Grounding prompts](https://github.com/personalaiengines/artha-terminal/blob/master/agent/prompts.py): `agent/prompts.py`
- [Analyst tools](https://github.com/personalaiengines/artha-terminal/blob/master/agent/tools.py): `agent/tools.py`
- [Provider routing](https://github.com/personalaiengines/artha-terminal/blob/master/agent/llm_client.py): `agent/llm_client.py`

### Research engines

- [Stock research](https://github.com/personalaiengines/artha-terminal/blob/master/services/stock_data.py): `services/stock_data.py`
- [F&O analysis](https://github.com/personalaiengines/artha-terminal/blob/master/services/fno_analysis.py): `services/fno_analysis.py`
- [F&O orchestration](https://github.com/personalaiengines/artha-terminal/blob/master/services/fno_service.py): `services/fno_service.py`
- [Risk engines](https://github.com/personalaiengines/artha-terminal/blob/master/engines/red_flags.py): `engines/red_flags.py`
- [News and search](https://github.com/personalaiengines/artha-terminal/blob/master/services/market_news.py): `services/market_news.py`

### Market data

- [Broker portfolio](https://github.com/personalaiengines/artha-terminal/blob/master/services/upstox.py): `services/upstox.py`
- [Market feeds](https://github.com/personalaiengines/artha-terminal/blob/master/services/upstox_stream.py): `services/upstox_stream.py`
- [Live fallback](https://github.com/personalaiengines/artha-terminal/blob/master/services/last_good.py): `services/last_good.py`
- [Scheduled ingestion](https://github.com/personalaiengines/artha-terminal/blob/master/ingestion/scheduler.py): `ingestion/scheduler.py`

### Data foundation

- [SQLite store](https://github.com/personalaiengines/artha-terminal/blob/master/db/__init__.py): `db/__init__.py`
- [Configuration](https://github.com/personalaiengines/artha-terminal/blob/master/config.py): `config.py`

### Other components

- **Researcher**

## Connections

- Researcher → Research pages: explores (evidence: `README.md`)
- Research pages → Charts: views charts (evidence: `README.md`)
- Research pages → Web API routes: requests data
- Web API routes → JSON and WS API: calls API
- JSON and WS API → Stock research: routes analysis (evidence: `api/server.py`)
- JSON and WS API → F&O orchestration: routes F&O (evidence: `api/server.py`)
- JSON and WS API → News and search: routes news (evidence: `api/server.py`)
- JSON and WS API → AI orchestration: runs analyst (evidence: `api/server.py`)
- JSON and WS API → Live socket: serves sockets (evidence: `api/server.py`)
- Live socket → Market feeds: streams ticks (evidence: `api/ws.py`)
- AI orchestration → Grounding prompts: builds prompts (evidence: `agent/orchestration.py`)
- AI orchestration → Provider routing: requests completion (evidence: `agent/orchestration.py`)
- AI orchestration → Analyst tools: dispatches tools (evidence: `agent/orchestration.py`)
- Analyst tools → Stock research: reads snapshots (evidence: `agent/tools.py`)
- Analyst tools → Risk engines: runs scans (evidence: `agent/tools.py`)
- Analyst tools → News and search: searches sources (evidence: `agent/tools.py`)
- F&O orchestration → F&O analysis: analyzes chain (evidence: `services/fno_service.py`)
- F&O orchestration → Broker portfolio: fetches options (evidence: `services/fno_service.py`)
- JSON and WS API → Broker portfolio: reads broker book (evidence: `README.md`)
- JSON and WS API → Live fallback: serves stale values (evidence: `README.md`)
- Scheduled ingestion → SQLite store: records jobs (evidence: `ingestion/scheduler.py`)
- Scheduled ingestion → Configuration: loads settings (evidence: `ingestion/scheduler.py`)
- JSON and WS API → SQLite store: reads market data (evidence: `api/server.py`)
- Market feeds → Live fallback: supports fallback
- Stock research → SQLite store: reads records (evidence: `services/stock_data.py`)
- Provider routing → Configuration: loads providers (evidence: `agent/llm_client.py`)