# faisalnwz01/ai-hedge-fund architecture

> Architecture diagram of the GitHub repository faisalnwz01/ai-hedge-fund, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/faisalnwz01/ai-hedge-fund
- Repository: https://github.com/faisalnwz01/ai-hedge-fund

## Overview

##### Project type and purpose
- This is a mono-repo containing two delivery targets:
a) A command-line AI Hedge Fund (Python CLI & backtester under `src/`)
b) A full-stack web application (`app/frontend` + `app/backend`)
- It’s a proof-of-concept POC for using multiple LLM-powered agents and financial data APIs to generate simulated trading decisions (educational use only).

##### File structure
- Top level:
- `.env.example`, `pyproject.toml` & `tests/` → Python CLI project
- `src/` → core CLI code: `agents/`, `backtester.py`, `main.py`, `llm/`, `graph/`, `tools/`, `utils/`
- `app/` → full-stack web app
– `app/backend/` → Python FastAPI service (Alembic migrations, SQLAlchemy models, repositories, services, routes)
– `app/frontend/` → React/TypeScript SPA (Vite, Tailwind, custom UI components, data & service layers)
– `app/run.sh` & `app/run.bat` spin up both frontend & backend
- `docker/` → Dockerfile, docker-compose for containerized deployment

##### README for additional insights
- Two modes of operation: CLI (`poetry run python src/main.py` or `docker run backtest`) vs. Web UI (`app/run.sh`)
- External dependencies: LLM APIs (OpenAI, Groq, Anthropic, local Ollama), financial data APIs
- Persistent state for web app stored in a SQL database (configured via Alembic + `database/connection.py`)

##### Essential details
- Every layer and major directory as a component
- Do not omit the LLM and financial-data integrations—they are central to the architecture
- Alembic migrations as part of the Database provisioning
- For the SPA, you may further group UI components vs. state/context providers vs. graph editor modules if space allows

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% CLI Application
  subgraph "CLI Application" 
    Orchestrator["Orchestrator\n(src/main.py)"]:::cli
    Agents["Agents Module\n(src/agents/)"]:::cli
    Backtester["Backtester Service\n(src/backtester.py)"]:::cli
    DataAdapter["Data Adapter / Cache\n(src/data/cache.py)"]:::cli
    subgraph "LLM Interface / Adapters"
      GenericLLM["Generic LLM Utilities\n(src/utils/llm.py)"]:::cli
      Ollama["Ollama Adapter\n(src/utils/ollama.py)"]:::cli
      LLModels["LLM Models & Configs\n(src/llm/)"]:::cli
    end
    Utils["Tools & Helpers\n(src/tools/, src/utils/)"]:::cli
  end

  %% Web Frontend
  subgraph "Web Frontend (React SPA)" 
    FEEntry["Entry Point\n(main.tsx / index.html)"]:::frontend
    UIComponents["UI Components\n(src/components/)"]:::frontend
    GraphEditor["Graph Editor / Flow Builder\n(src/components/Flow.tsx)"]:::frontend
    ServicesFE["Client-side Services\n(src/services/)"]:::frontend
    StateCtx["State & Context Providers\n(src/contexts/)"]:::frontend
    Hooks["Hooks & Data Layer\n(src/hooks/)"]:::frontend
  end

  %% Web Backend
  subgraph "Web Backend (FastAPI)" 
    BEEntry["Entry Point\n(main.py)"]:::backend
    Routes["API Routes\n(app/backend/routes/)"]:::backend
    ServicesBE["Business Logic / Services\n(app/backend/services/)"]:::backend
    Repos["Repositories\n(app/backend/repositories/)"]:::backend
    DBLayer["DB Connection & Models\n(app/backend/database/connection.py)"]:::backend
    Schemas["Pydantic Schemas & Events\n(app/backend/models/schemas.py)"]:::backend
    Migrations["Alembic Migrations\n(app/backend/alembic/)"]:::backend
  end

  %% Database
  subgraph "Database"
    Database["SQL Database"]:::db
  end

  %% External Services
  subgraph "External Services"
    LLMAPIs["LLM APIs\n(OpenAI, Groq, Ollama)"]:::external
    DataAPI["Financial Data API"]:::external
  end

  %% CLI Flows
  Orchestrator --> Agents
  Orchestrator --> Backtester
  Orchestrator --> DataAdapter
  Orchestrator --> GenericLLM
  Orchestrator --> Ollama
  Orchestrator --> LLModels
  Orchestrator --> Utils

  Agents --> LLMAPIs
  DataAdapter --> DataAPI
  GenericLLM --> LLMAPIs
  Ollama --> LLMAPIs
  Backtester --> DataAdapter
  Backtester --> GenericLLM

  %% Frontend Flows
  FEEntry --> UIComponents
  FEEntry --> GraphEditor
  FEEntry --> ServicesFE
  ServicesFE --> StateCtx
  ServicesFE --> Hooks
  GraphEditor --> Hooks

  UIComponents -->|"HTTP/REST"| Routes
  ServicesFE -->|"HTTP/REST"| Routes

  %% Backend Flows
  Routes --> ServicesBE
  ServicesBE --> Repos
  ServicesBE --> LLMAPIs
  ServicesBE --> DataAPI
  Repos --> DBLayer
  DBLayer --> Database
  Migrations --> Database

  %% Click Events
  click Orchestrator "https://github.com/faisalnwz01/ai-hedge-fund/blob/main/src/main.py"
  click Agents "https://github.com/faisalnwz01/ai-hedge-fund/tree/main/src/agents/"
  click Backtester "https://github.com/faisalnwz01/ai-hedge-fund/blob/main/src/backtester.py"
  click DataAdapter "https://github.com/faisalnwz01/ai-hedge-fund/blob/main/src/data/cache.py"
  click GenericLLM "https://github.com/faisalnwz01/ai-hedge-fund/blob/main/src/utils/llm.py"
  click Ollama "https://github.com/faisalnwz01/ai-hedge-fund/blob/main/src/utils/ollama.py"
  click LLModels "https://github.com/faisalnwz01/ai-hedge-fund/tree/main/src/llm/"
  click FEEntry "https://github.com/faisalnwz01/ai-hedge-fund/blob/main/app/frontend/src/main.tsx"
  click UIComponents "https://github.com/faisalnwz01/ai-hedge-fund/tree/main/app/frontend/src/components/"
  click GraphEditor "https://github.com/faisalnwz01/ai-hedge-fund/blob/main/app/frontend/src/components/Flow.tsx"
  click ServicesFE "https://github.com/faisalnwz01/ai-hedge-fund/tree/main/app/frontend/src/services/"
  click StateCtx "https://github.com/faisalnwz01/ai-hedge-fund/tree/main/app/frontend/src/contexts/"
  click Hooks "https://github.com/faisalnwz01/ai-hedge-fund/tree/main/app/frontend/src/hooks/"
  click BEEntry "https://github.com/faisalnwz01/ai-hedge-fund/blob/main/app/backend/main.py"
  click Routes "https://github.com/faisalnwz01/ai-hedge-fund/tree/main/app/backend/routes/"
  click ServicesBE "https://github.com/faisalnwz01/ai-hedge-fund/tree/main/app/backend/services/"
  click Repos "https://github.com/faisalnwz01/ai-hedge-fund/tree/main/app/backend/repositories/"
  click DBLayer "https://github.com/faisalnwz01/ai-hedge-fund/blob/main/app/backend/database/connection.py"
  click Schemas "https://github.com/faisalnwz01/ai-hedge-fund/blob/main/app/backend/models/schemas.py"
  click Migrations "https://github.com/faisalnwz01/ai-hedge-fund/tree/main/app/backend/alembic/"

  %% Styles
  classDef cli fill:#ffe4b5,stroke:#d2691e,stroke-width:1px
  classDef frontend fill:#b3d9ff,stroke:#1f77b4,stroke-width:1px
  classDef backend fill:#b3ffb3,stroke:#2ca02c,stroke-width:1px
  classDef db fill:#ffffb3,stroke:#ff7f0e,stroke-width:1px
  classDef external fill:#e0e0e0,stroke:#7f7f7f,stroke-width:1px
```
