# office365/financial-agent-india architecture

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

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

## Overview

##### What this project is (type + purpose)
This repo is a **Python CLI-style “agent” toolkit** (not a deployed service) that:
- Authenticates to **AngelOne SmartAPI** (Indian market brokerage API)
- Fetches **equity OHLCV** (and optionally **options chain** with Greeks/IV/OI)
- Sends structured market data to **Anthropic Claude** for **LLM-driven analysis**
- Includes a **reference order placement** script (dry-run by default)

So your “system” is primarily: **User → Python scripts → external APIs (AngelOne, Anthropic)** with credentials loaded from `.env`.

##### File tree into architectural components
Use the file tree as your authoritative decomposition (each file is effectively a component/module boundary):

- **Configuration / Secrets**
- `.env.example`, `config.py`
- Responsibility: load API keys, client ID/password, TOTP secret, Anthropic key.

- **Brokerage API Integration (AngelOne SmartAPI)**
- `connect.py`
- Responsibility: login + session creation (tokens like session/feed token).
- (Implicit sub-responsibilities: TOTP generation, error handling)

- **Market Data Retrieval**
- `fetch_data.py`
- Responsibility: pull 30 days daily candles (OHLCV) for a symbol token.
- Data output: printed table / returned data structure.

- **LLM Agent (Core Analysis)**
- `agent.py`
- Responsibility: orchestrate connect → fetch equity candles → prompt Claude → parse/print structured analysis.

- **LLM Agent (Enhanced with Options)**
- `agent_with_options.py`
- Responsibility: connect → fetch equity candles + options chain → prompt Claude with combined context → parse/print deeper analysis.

- **Trading Action (Scaffold)**
- `place_order.py`
- Responsibility: demonstrate SmartAPI order placement flow; gated by `DRY_RUN`.

- **Project dependencies**
- `requirements.txt`

This structure strongly suggests a **pipeline/orchestrator pattern** (agent scripts orchestrate calls) rather than layered web architecture.

##### Python Runtime / Scripts
- `agent.py`
- `agent_with_options.py`
- `fetch_data.py`
- `connect.py`
- `place_order.py`
- `config.py` (shared config/secrets loader)

##### AngelOne SmartAPI
- Auth endpoint (session/token)
- Market data endpoints (candles, quotes)
- Options chain endpoints
- Order endpoints
- (Optional future: WebSocket streaming, but not shown as implemented unless you add it)
##### Anthropic API (Claude)
- Prompt + response for analysis

##### Credentials/Secrets
- From `.env`: API keys, client creds, TOTP secret
##### Session Tokens
- Session token / feed token returned by SmartAPI login
##### Market Data Payloads
- OHLCV candles
- Options chain snapshot (IV/OI/Greeks)
##### LLM Prompt + Structured Output
- Trend/support/resistance/volume summary (+ options interpretation)

##### User → `agent.py`
- Inputs: `--symbol`, `--token` (or defaults)
##### `agent.py` → `config.py`
- Reads `.env` secrets
##### `agent.py` → `connect.py` → AngelOne SmartAPI (Auth)
- Sends: client ID + password + TOTP + API key
- Receives: session token, feed token
##### `agent.py` → AngelOne SmartAPI (Market Data)
- Requests: historical candles (30 days daily OHLCV)
- Receives: OHLCV array/time series
##### `agent.py` → Anthropic Claude
- Sends: prompt containing OHLCV (and any derived stats) + instructions for structured output
- Receives: structured analysis text/JSON-like output
##### `agent.py` → User
- Prints formatted report

##### Enhanced flow (agent_with_options.py)
Same as above, plus:
- **`agent_with_options.py` → AngelOne SmartAPI (Options Chain)**
- Receives: chain with IV/OI/Greeks
- **`agent_with_options.py` → Claude**
- Sends: combined equity candles + options chain context

##### Order scaffold flow (place_order.py)
- **User → `place_order.py`**
- **`place_order.py` → connect/auth → SmartAPI order endpoint**
- Explicitly annotate **DRY_RUN gate**:
- If `DRY_RUN=True`, no external order call is executed (or request is not sent).

##### Architectural patterns / design principles to highlight

- **Orchestrator scripts**: `agent.py` and `agent_with_options.py` orchestrate multiple integrations.
- **Integration boundaries**:
- “Brokerage API boundary” (SmartAPI)
- “LLM boundary” (Anthropic)
- **Credential isolation**: `.env` + `config.py` as the single source of secrets.
- **Session-based auth**: SmartAPI login yields tokens used for subsequent calls.

Use this as your “component inventory” so you don’t miss anything:

- **Local Execution Environment**
- Python 3.8+
- `requirements.txt` dependencies (SDKs for SmartAPI + Anthropic; TOTP library likely)

- **Config/Security**
- `.env` (ANGELONE_API_KEY, CLIENT_ID, PASSWORD, TOTP_SECRET, ANTHROPIC_API_KEY)
- `config.py` (loader)

- **SmartAPI Integration**
- `connect.py` (auth/session token generation)
- Data endpoints used by `fetch_data.py` / agents
- Order endpoint used by `place_order.py`

- **LLM Integration**
- Prompt construction in `agent.py` / `agent_with_options.py`
- Output parsing/formatting (even if lightweight, show it as “Response formatting”)

##### “Don’t overthink it” rule for this repo
- Treating **each script as a first-class component**
- Treating **AngelOne** and **Anthropic** as distinct external subsystems
- Explicitly drawing **session/token** and **prompt/response** flows

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Global Actors / Context
  %% =========================
  User["CLI User (Trader/Developer)"]:::actor

  %% =========================
  %% Local Execution Boundary
  %% =========================
  subgraph "Local Machine / Python Runtime (CLI Toolkit)"
    direction TB

    subgraph "Configuration / Secrets"
      direction TB
      Env[("Secrets (.env)")]:::secrets
      Config["config.py\n(Secrets Loader)"]:::internal
      Req["requirements.txt\n(Dependencies)"]:::internal
    end

    subgraph "Orchestrators (Agents)"
      direction TB
      Agent["agent.py\n(Core Analysis Orchestrator)"]:::internal
      AgentOpt["agent_with_options.py\n(Enhanced w/ Options)"]:::internal
      Report["Console Output\n(Formatted Report)"]:::output
    end

    subgraph "Integrations / Utilities"
      direction TB
      Connect["connect.py\n(SmartAPI Auth + Session)"]:::internal
      Fetch["fetch_data.py\n(Equity OHLCV Retrieval)"]:::internal
      Place["place_order.py\n(Order Scaffold)"]:::internal
      DryRun{"DRY_RUN = True?"}:::control
    end

    subgraph "Data Objects (In-Memory)"
      direction TB
      Creds["Credentials\n(API key, Client ID, Password, TOTP, Anthropic key)"]:::secrets
      Tokens["Session Tokens\n(session_token, feed_token)"]:::secrets
      Ohlcv["Market Data Payload\n(30D Daily OHLCV Candles)"]:::data
      OptChain["Options Chain Snapshot\n(IV/OI/Greeks)"]:::data
      Prompt["LLM Prompt\n(Instructions + Market Context)"]:::data
      Analysis["LLM Structured Output\n(Trend/SR/Volume + Options Read)"]:::data
    end
  end

  %% =========================
  %% External Vendor Boundaries
  %% =========================
  subgraph "AngelOne SmartAPI (External Vendor)"
    direction TB
    SmartAuth["Auth Endpoint\n(Login + TOTP)"]:::external
    SmartMkt["Market Data Endpoints\n(Historical Candles/Quotes)"]:::external
    SmartOpt["Options Chain Endpoints\n(Greeks/IV/OI)"]:::external
    SmartOrd["Order Endpoints\n(Place/Modify)"]:::external
  end

  subgraph "Anthropic API (External Vendor)"
    direction TB
    Claude["Claude (LLM) Endpoint\n(Prompt → Analysis)"]:::external
  end

  %% =========================
  %% Core Flow: agent.py
  %% =========================
  User -->|"runs agent.py (--symbol/--token)"| Agent
  Agent -->|"load secrets"| Config
  Env -->|"read .env"| Config
  Config -->|"materialize"| Creds

  Agent -->|"authenticate"| Connect
  Creds -->|"client creds + TOTP + API key"| Connect
  Connect -->|"login request"| SmartAuth
  SmartAuth -->|"session/feed tokens"| Connect
  Connect -->|"return tokens"| Tokens
  Tokens -->|"use token"| Agent

  Agent -->|"fetch candles"| Fetch
  Tokens -->|"authorize"| Fetch
  Fetch -->|"historical candles req"| SmartMkt
  SmartMkt -->|"OHLCV array"| Fetch
  Fetch -->|"return OHLCV"| Ohlcv
  Ohlcv -->|"context"| Agent

  Agent -->|"build prompt"| Prompt
  Ohlcv -->|"include OHLCV"| Prompt
  Prompt -->|"send prompt"| Claude
  Claude -->|"analysis response"| Analysis
  Analysis -->|"format/print"| Report
  Report -->|"view report"| User

  %% =========================
  %% Enhanced Flow: agent_with_options.py
  %% =========================
  User -->|"runs agent_with_options.py"| AgentOpt
  AgentOpt -->|"load secrets"| Config
  AgentOpt -->|"authenticate"| Connect
  Tokens -->|"use token"| AgentOpt

  AgentOpt -->|"fetch candles"| Fetch
  Fetch -->|"OHLCV"| Ohlcv

  AgentOpt -->|"fetch options chain"| SmartOpt
  SmartOpt -->|"IV/OI/Greeks"| OptChain

  Ohlcv -->|"combine context"| Prompt
  OptChain -->|"combine context"| Prompt
  AgentOpt -->|"send combined prompt"| Claude
  Claude -->|"deeper analysis"| Analysis
  Analysis -->|"format/print"| Report

  %% =========================
  %% Order Scaffold: place_order.py (DRY_RUN gate)
  %% =========================
  User -->|"runs place_order.py"| Place
  Place -->|"load secrets"| Config
  Place -->|"authenticate"| Connect
  Place -->|"evaluate safety gate"| DryRun
  DryRun -->|"Yes (default): no external order call"| Report
  DryRun -->|"No: execute order request"| SmartOrd
  SmartOrd -->|"order response"| Report

  %% =========================
  %% Trust / Boundary Notes
  %% =========================
  Creds -.->|"sent only as required"| SmartAuth
  Tokens -.->|"used for subsequent calls"| SmartMkt
  Tokens -.->|"used for subsequent calls"| SmartOpt
  Tokens -.->|"used for subsequent calls"| SmartOrd

  %% =========================
  %% Click Events (Component Mapping)
  %% =========================
  click Env "https://github.com/office365/financial-agent-india/blob/main/.env.example"
  click Config "https://github.com/office365/financial-agent-india/blob/main/config.py"
  click Connect "https://github.com/office365/financial-agent-india/blob/main/connect.py"
  click Fetch "https://github.com/office365/financial-agent-india/blob/main/fetch_data.py"
  click Agent "https://github.com/office365/financial-agent-india/blob/main/agent.py"
  click AgentOpt "https://github.com/office365/financial-agent-india/blob/main/agent_with_options.py"
  click Place "https://github.com/office365/financial-agent-india/blob/main/place_order.py"
  click Req "https://github.com/office365/financial-agent-india/blob/main/requirements.txt"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#E8F1FF,stroke:#2B6CB0,stroke-width:1.5px,color:#0B1F3A
  classDef internal fill:#EAF7EA,stroke:#2F855A,stroke-width:1.5px,color:#12341F
  classDef external fill:#FFF4E5,stroke:#B7791F,stroke-width:1.5px,color:#3A2506
  classDef secrets fill:#FFE6EE,stroke:#B83280,stroke-width:1.5px,color:#3B0A1E
  classDef data fill:#F2F2FF,stroke:#5A67D8,stroke-width:1.5px,color:#1A1E3A
  classDef output fill:#E6FFFA,stroke:#2C7A7B,stroke-width:1.5px,color:#0F2D2E
  classDef control fill:#FFF5F5,stroke:#C53030,stroke-width:2px,color:#3B0B0B
```
