# am1403x/financial-agent-india architecture

> Architecture diagram of the GitHub repository am1403x/financial-agent-india, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/am1403x/financial-agent-india
- Repository: https://github.com/am1403x/financial-agent-india

## Overview

This repo is a **Python CLI-based “financial analysis agent”** (not a web app, not a service) that:
- Authenticates to **AngelOne SmartAPI** (with **API key + client credentials + TOTP**) to obtain session/feed tokens
- Fetches **market data** (cash OHLCV candles; optionally options chain/Greeks)
- Sends structured data to **Anthropic Claude API**
- Prints a **structured technical/options analysis report**
- Includes a **reference order placement script** (dry-run by default)

##### File tree → architectural components

- `config.py`
- **Configuration/Secrets Loader**: reads `.env` (from `.env.example` template)
- Outputs: `ANGELONE_*`, `ANTHROPIC_API_KEY`

- `connect.py`
- **SmartAPI Auth Session Factory**
- Inputs: client ID, password, TOTP secret, API key
- Outputs: authenticated SmartAPI session + session token/feed token

- `fetch_data.py`
- **Market Data Retrieval**
- Calls SmartAPI endpoints for **30 days daily OHLCV** (per README)
- Output: normalized candle series used by the agent

- `agent.py`
- **Core Agent Orchestrator**
- Orchestration flow: connect → fetch candles → create prompt → call Claude → parse/format structured output

- `agent_with_options.py`
- **Enhanced Agent Orchestrator**
- Everything in `agent.py` plus:
- **Options Chain Retrieval** from SmartAPI (IV, OI, Greeks)
- Combines options signals + price action before calling Claude (or sends both to Claude)

- `place_order.py`
- **Trade Execution Adapter (reference)**
- SmartAPI order placement scaffolding (dry-run default)

- `requirements.txt`
- Dependency boundary indicator (external libs, SmartAPI SDK, Anthropic SDK, dotenv, etc.)

##### CLI Entry Points
- `agent.py`
- `agent_with_options.py`
- `fetch_data.py`
- `connect.py`
- `place_order.py`

##### Config/Security
- `config.py` + `.env`
- Secrets (API keys, password, TOTP secret)

##### SmartAPI Adapter
- Session/auth generation (from `connect.py`)
- Data endpoints (candles, option chain)
- Order endpoint (place order)

##### LLM Adapter
- Claude API call (within agent scripts)
- Prompt construction + response parsing/formatting (within agent scripts)

- **AngelOne SmartAPI**
- Auth
- Market data (candles, option chain)
- Orders (optional)

- **Anthropic Claude API**
- Model inference endpoint

- Credentials: API key/clientID/password/TOTP secret
- Session artifacts: session token / feed token
- Market data: OHLCV candle series (30 days daily)
- Options data: chain + IV/OI/Greeks
- Prompt payload: structured JSON/text sent to Claude
- Result: structured analysis (trend/support/resistance/volume + summary)

##### `agent.py` calls `connect.py` to
- Generate TOTP
- Authenticate SmartAPI
- Receive session/feed tokens
##### `agent.py` formats and prints report

For `agent_with_options.py`, insert:
- Fetch options chain from SmartAPI
- Merge options signals + price candles before step 5

For `place_order.py`, show it as:
- Separate CLI path: load config → connect → (dry-run) → SmartAPI placeOrder()

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% A) SYSTEM CONTEXT (C4 L1)
  %% =========================================================
  subgraph CTX["A) System Context (C4 Level 1)"]
    direction TB

    U["User\n(Runs CLI; provides symbol + token)"]:::actor
    CLI_CTX["Financial Analysis Agent CLI\n(Python scripts in this repo)"]:::internal

    SVC_SMART(("AngelOne SmartAPI\n(Auth + Market Data + Orders)")):::external
    SVC_CLAUDE(("Anthropic Claude API\n(LLM Inference)")):::external

    U -->|"CLI_args(symbol,token)"| CLI_CTX
    CLI_CTX -->|"auth+data_requests"| SVC_SMART
    SVC_SMART -->|"OHLCV_candles(30d_daily)"| CLI_CTX
    CLI_CTX -.->|"optional:placeOrder(dry_run_default)"| SVC_SMART

    CLI_CTX -->|"prompt_payload(structured_data)"| SVC_CLAUDE
    SVC_CLAUDE -->|"structured_analysis_report"| CLI_CTX
    CLI_CTX -->|"prints_report"| U
  end

  %% =========================================================
  %% B) RUNTIME / CONTAINER BOUNDARY (CLI "containers")
  %% =========================================================
  subgraph RUN["B) Runtime Boundary (C4 Level 2-ish for a CLI)"]
    direction TB

    subgraph TRUST["Local Machine / Developer Environment (Trust Boundary)"]
      direction TB

      ENV[("Secrets Store\n.env / environment variables")]:::datastore
      CFG["config.py\nConfiguration/Secrets Loader"]:::internal

      PROC["Python CLI Process\n(single runtime; no server; no DB)"]:::process

      REQ["requirements.txt\nDependency Boundary (SDKs/libs)"]:::boundary
      DOC["README.md\nUsage/CLI docs"]:::doc

      ENV -->|"loads"| CFG
      CFG -->|"exports:ANGELONE_*,ANTHROPIC_API_KEY"| PROC
      REQ -->|"installs_deps_for"| PROC
      DOC -->|"guides_user"| PROC
    end

    PROC -->|"HTTPS/SDK_calls"| SVC_SMART
    PROC -->|"HTTPS_calls"| SVC_CLAUDE

    NOTE_NODB["Note: No database and no server\n(only local CLI runtime)"]:::note
    TRUST --- NOTE_NODB
  end

  %% =========================================================
  %% C) COMPONENT + DATA-FLOW / SEQUENCE (MOST IMPORTANT)
  %% =========================================================
  subgraph SEQ["C) Component + Data-Flow (Pipeline/Orchestrator)"]
    direction TB

    subgraph ENTRY["CLI Entry Points (Analysis)"]
      direction TB
      AG["agent.py\nCore Agent Orchestrator"]:::internal
      AGOPT["agent_with_options.py\nEnhanced Agent Orchestrator"]:::internal
    end

    subgraph CONFIG["Config/Security"]
      direction TB
      ENV2[(" .env / env vars ")]:::datastore
      CFG2["config.py\nLoad secrets (API keys, password, TOTP secret)"]:::internal
      ENV2 -->|"read"| CFG2
    end

    subgraph SMART_ADAPTER["AngelOne SmartAPI Adapter (Gateway)"]
      direction TB
      CONN["connect.py\nTOTP + login → session/feed tokens"]:::internal
      FETCH["fetch_data.py\nMarket Data Retrieval\n(30d daily OHLCV)"]:::internal
      ORDER["place_order.py\nTrade Execution Adapter\n(reference; dry-run default)"]:::internal
    end

    subgraph LLM_ADAPTER["LLM Adapter (Gateway)"]
      direction TB
      PROMPT["Prompt Builder\n(structured payload)"]:::internal
      PARSE["Parse/Format Report\n(structured output)"]:::internal
      OUT["Console Output\n(printed report)"]:::output
    end

    %% --- Core flow (agent.py)
    AG -->|"loads_config"| CFG2
    CFG2 -->|"credentials(API_key,clientID,password,TOTP_secret)"| CONN
    AG -->|"auth_request"| CONN
    CONN -->|"session_token+feed_token"| AG
    AG -->|"fetch_candles(symbol,token)"| FETCH
    FETCH -->|"OHLCV_candle_series(30d_daily)"| AG
    AG -->|"build_prompt_data"| PROMPT
    PROMPT -->|"prompt_payload"| SVC_CLAUDE
    SVC_CLAUDE -->|"analysis(response)"| PARSE
    PARSE -->|"formatted_report"| OUT

    %% --- Enhanced flow (agent_with_options.py)
    AGOPT -->|"loads_config"| CFG2
    AGOPT -->|"auth_request"| CONN
    CONN -->|"session_token+feed_token"| AGOPT
    AGOPT -->|"fetch_candles"| FETCH
    FETCH -->|"OHLCV_candles"| AGOPT

    OPTS["Options Chain Retrieval\n(IV/OI/Greeks)"]:::internal
    AGOPT -.->|"optional:fetch_options_chain"| OPTS
    OPTS -.->|"options_chain+greeks"| AGOPT

    AGOPT -->|"merge_price+options"| PROMPT
    PROMPT -->|"prompt_payload"| SVC_CLAUDE
    SVC_CLAUDE -->|"analysis(response)"| PARSE
    PARSE -->|"formatted_report"| OUT

    %% --- Separate optional execution path (place_order.py)
    ORDER -->|"loads_config"| CFG2
    ORDER -->|"auth_request"| CONN
    CONN -->|"session_token"| ORDER
    ORDER -.->|"optional:placeOrder(dry_run_default)"| SVC_SMART

    %% --- SmartAPI interactions (data + auth)
    CONN -->|"login+TOTP"| SVC_SMART
    SVC_SMART -->|"session/feed_tokens"| CONN
    FETCH -->|"candle_endpoint_requests"| SVC_SMART
    SVC_SMART -->|"OHLCV_candles"| FETCH
    OPTS -.->|"option_chain_endpoint_requests"| SVC_SMART
    SVC_SMART -.->|"chain+IV/OI/Greeks"| OPTS

    %% Legend/notes
    LEG["Legend:\nBlue=internal modules\nGray=cylinders=config store\nOrange=external services\nDashed=optional/conditional"]:::note
  end

  %% =========================================================
  %% Click events (from component_mapping)
  %% =========================================================
  click CFG "https://github.com/am1403x/financial-agent-india/blob/main/config.py"
  click CONN "https://github.com/am1403x/financial-agent-india/blob/main/connect.py"
  click FETCH "https://github.com/am1403x/financial-agent-india/blob/main/fetch_data.py"
  click AG "https://github.com/am1403x/financial-agent-india/blob/main/agent.py"
  click AGOPT "https://github.com/am1403x/financial-agent-india/blob/main/agent_with_options.py"
  click ORDER "https://github.com/am1403x/financial-agent-india/blob/main/place_order.py"
  click REQ "https://github.com/am1403x/financial-agent-india/blob/main/requirements.txt"
  click DOC "https://github.com/am1403x/financial-agent-india/blob/main/README.md"
  click ENV "https://github.com/am1403x/financial-agent-india/blob/main/.env.example"
  click ENV2 "https://github.com/am1403x/financial-agent-india/blob/main/.env.example"

  %% =========================================================
  %% Styles
  %% =========================================================
  classDef internal fill:#1f6feb,stroke:#0b3d91,color:#ffffff,stroke-width:1px
  classDef process fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1px
  classDef external fill:#f59e0b,stroke:#b45309,color:#111827,stroke-width:1px
  classDef datastore fill:#9ca3af,stroke:#4b5563,color:#111827,stroke-width:1px
  classDef actor fill:#22c55e,stroke:#166534,color:#052e16,stroke-width:1px
  classDef output fill:#a855f7,stroke:#6b21a8,color:#ffffff,stroke-width:1px
  classDef boundary fill:#334155,stroke:#0f172a,color:#ffffff,stroke-width:1px
  classDef doc fill:#14b8a6,stroke:#0f766e,color:#042f2e,stroke-width:1px
  classDef note fill:#fde68a,stroke:#b45309,color:#111827,stroke-width:1px
```
