# sunnysavita10/agentic-trading-bot architecture

> Architecture diagram of the GitHub repository sunnysavita10/agentic-trading-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sunnysavita10/agentic-trading-bot
- Repository: https://github.com/sunnysavita10/agentic-trading-bot

## Overview

##### Project type and purpose
- This is a full-stack, AI-driven trading system written in Python.
- It exposes a FastAPI backend (main.py) and a Streamlit frontend (streamlit_ui.py).
- Core responsibilities: fetch real‐time market data, run ingestion pipelines, execute an “agent” workflow (trading logic + LLM prompts), and optionally persist/query embeddings via Pinecone or similar.

##### File structure
- Top-level:
- Pipfile/requirements.txt, setup.py – dependency & packaging
- main.py (FastAPI app)
- streamlit_ui.py (frontend)
- config/config.yaml & utils/config_loader.py
- Directories by layer:
- data_ingestion/ingestion_pipeline.py – ETL of market data
- data_models/models.py – Pydantic or ORM schemas
- agent/workflow.py – orchestrates decision logic + prompts
- prompt_library/prompt.py – prompt templates
- toolkit/tools.py – utility functions for trading & LLM
- utils/model_loaders.py – loads ML/LLM models or vector stores
- custom_logging & exception – cross‐cutting concerns for logging and errors
- fallback_data – local docs for offline use
- notebook – exploratory experiments (ipynb)

##### README for architecture hints
- Requires several external API keys (Polygon, Google, TAVILY, GROQ, Pinecone)
- Two entry points:
- `uvicorn main:app` (backend API)
- `streamlit run streamlit_ui.py` (frontend)
- Encourages logging, exception capturing, and eventual deployment.

a. Main components:
1. Client & UI Layer:
- Browser / user interacts with Streamlit UI
2. Frontend (Streamlit):
- Calls FastAPI endpoint(s) for data & trades
3. Backend (FastAPI App):
- HTTP API routes in main.py
- Dependency injection of config_loader, logger, exception handlers
4. Core Services:
- Data Ingestion Service
- Agent Workflow Service
- Prompt Library & Toolkit
5. Data Models Layer
6. External Services:
- Market Data APIs (Polygon, Google, TAVILY)
- LLM APIs (GROQ)
- Vector DB / Embeddings (Pinecone)
7. Fallback Data Store (local PDFs/docs) for offline mode
b. Relationships & interactions:
- Streamlit UI → FastAPI (REST calls)
- FastAPI routes → Services (via DI or direct calls)
- Data Ingestion → External Market APIs → normalized by data_models → passed to Agent
- Agent Workflow → prompt_library & toolkit → LLM APIs → receives suggestions/trade signals
- Agent → executes trades or writes results back via FastAPI response
- Optionally Agent or ingestion writes/query embeddings to Pinecone via model_loaders
- All components use custom_logging/my_logger and exception handlers
c. Architectural patterns & design principles:
- Layered (presentation, application, domain, infrastructure)
- Separation of concerns: ingestion vs. workflow vs. storage vs. UI
- Dependency Injection for config, logging, and exceptions
- Pluggable modules: prompt_library and toolkit abstract external LLM calls
d. Key technologies/frameworks:
- Python 3.10, FastAPI, Uvicorn
- Streamlit for UI
- Pydantic (data_models)
- YAML config, custom config_loader
- Third-party APIs (Polygon, GROQ, Pinecone)
- Local fallback docs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client & UI Layer
    subgraph "Client & UI Layer"
        Browser["Browser"]:::external
        Streamlit["Streamlit UI"]:::frontend
    end
    Browser -->|"interacts"| Streamlit
    click Streamlit "https://github.com/sunnysavita10/agentic-trading-bot/blob/main/streamlit_ui.py"

    %% Backend Entry Point
    subgraph "Backend (FastAPI App)"
        API["FastAPI App (main.py)"]:::backend
    end
    Streamlit -->|"REST HTTP"| API
    click API "https://github.com/sunnysavita10/agentic-trading-bot/blob/main/main.py"

    %% Configuration
    ConfigLoader["Config Loader"]:::backend
    ConfigFile["Configuration File"]:::backend
    API -->|"loads settings"| ConfigLoader
    ConfigLoader -->|"reads"| ConfigFile
    click ConfigLoader "https://github.com/sunnysavita10/agentic-trading-bot/blob/main/utils/config_loader.py"
    click ConfigFile "https://github.com/sunnysavita10/agentic-trading-bot/blob/main/config/config.yaml"

    %% Cross-cutting Concerns
    Logger["Custom Logging"]:::cross
    Exception["Exception Handling"]:::cross
    API --> Logger
    API --> Exception
    ConfigLoader --> Logger
    ConfigLoader --> Exception
    click Logger "https://github.com/sunnysavita10/agentic-trading-bot/blob/main/custom_logging/my_logger.py"
    click Exception "https://github.com/sunnysavita10/agentic-trading-bot/blob/main/exception/exceptions.py"

    %% Core Services
    subgraph "Core Services"
        Ingestion["Data Ingestion Service"]:::backend
        Models["Data Models"]:::backend
        Agent["Agent Workflow Service"]:::backend
        PromptLib["Prompt Library"]:::backend
        Toolkit["Toolkit"]:::backend
        ModelLoader["Model & Vector Store Loader"]:::backend
        Storage["Fallback Data Store"]:::db
    end
    API -->|"invoke"| Ingestion
    API -->|"invoke"| Agent
    click Ingestion "https://github.com/sunnysavita10/agentic-trading-bot/blob/main/data_ingestion/ingestion_pipeline.py"
    click Models "https://github.com/sunnysavita10/agentic-trading-bot/blob/main/data_models/models.py"
    click Agent "https://github.com/sunnysavita10/agentic-trading-bot/blob/main/agent/workflow.py"
    click PromptLib "https://github.com/sunnysavita10/agentic-trading-bot/blob/main/prompt_library/prompt.py"
    click Toolkit "https://github.com/sunnysavita10/agentic-trading-bot/blob/main/toolkit/tools.py"
    click ModelLoader "https://github.com/sunnysavita10/agentic-trading-bot/blob/main/utils/model_loaders.py"
    click Storage "https://github.com/sunnysavita10/agentic-trading-bot/tree/main/fallback_data/"

    %% Data Ingestion Flow
    ExternalMarket["Market Data APIs"]:::external
    Ingestion -->|"fetch data (JSON)"| ExternalMarket
    ExternalMarket -->|"data JSON"| Ingestion
    Ingestion -->|"normalize"| Models
    Models --> Agent

    %% Agent Workflow
    PromptLib -->|"templates"| Agent
    Toolkit -->|"utilities"| Agent

    %% LLM & Vector DB Integrations
    LLMAPI["LLM APIs (GROQ)"]:::external
    VectorDB["Vector DB (Pinecone)"]:::external
    Agent -->|"LLM calls"| LLMAPI
    LLMAPI -->|"response"| Agent
    Agent -->|"store/query embeddings"| ModelLoader
    ModelLoader -->|"embeddings"| VectorDB
    VectorDB -->|"embeddings"| ModelLoader

    %% Fallback Data
    Agent -.->|"offline docs"| Storage

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef backend  fill:#E2F0D9,stroke:#228B22,color:#228B22;
    classDef external fill:#FFF1C1,stroke:#FFA500,color:#FFA500;
    classDef cross    fill:#F0F0F0,stroke:#A9A9A9,color:#666666;
    classDef db       fill:#F3E5AB,stroke:#B8860B,color:#B8860B;
```
