# virattt/financial-agent-ui architecture

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

- Interactive diagram: https://gitdiagram.com/virattt/financial-agent-ui
- Repository: https://github.com/virattt/financial-agent-ui

## Overview

##### Project type and purpose
- This is a full-stack, containerized generative-AI financial agent UI.
- Frontend: Next.js/React app written in TypeScript, styled with Tailwind, runs in a Node.js container.
- Backend: Python service using LangChain agents and Vercel AI SDK, orchestrating financial and web-search “tools,” runs in a Python container.
- External dependencies: OpenAI API, Financialdatasets.ai API, Tavily search API.

##### File structure
Top-level
- docker-compose.yml – spins up frontend & backend containers, wires network & env files.
- .env.example – shared environment variables for API keys and ports.
- backend/ – Python package (‘gen_ui_backend’) plus Dockerfile, Makefile, scripts, requirements.
- frontend/ – Next.js app directory, Dockerfile, package.json, Tailwind & PostCSS config, shared UI components under components/ui and prebuilt charts.

Patterns and architectural hints
- “gen_ui_backend/chain.py” and “server.py” imply an agent-orchestrator pattern (LangChain agents + HTTP API).
- “tools” subpackages in backend each encapsulate a specific data-fetcher tool (prices, insider_transactions, web_search, financial search).
- Frontend under app/ uses React Server Components (layout.tsx, page.tsx) calling backend APIs.

##### Extract architectural insights from README
- The UI dynamically renders based on agent decisions (chain-of-thought → tool invocation → final JSON).
- Docker is the recommended run strategy; both services live on the same docker-compose network.

##### Diagramming the architecture
- User’s Web Browser (UI)
- Frontend Container (Next.js/React + Tailwind)
- Backend Container (Python + LangChain + Vercel AI SDK)
- External Services:
– OpenAI API (LLM calls)
– Financialdatasets.ai API (real-time stock & financial data)
– Tavily Search API (general web search)

1. Browser → Frontend (HTTPS, React pages & assets)
2. Frontend → Backend (HTTP POST /chat or /api endpoints with user prompt)
3. Backend → OpenAI API (LLM invocation via Vercel AI SDK)
4. Backend agent core decides which “tool” to call → calls Financialdatasets or Tavily API
5. Financialdatasets.ai and Tavily → return JSON data → agent processes & composes response
6. Backend → Frontend (JSON payload containing UI spec & data)
7. Frontend renders dynamic charts, tables, chat, etc.

c. Architectural patterns & design principles
- Agent-orchestrator pattern: single central chain.py that sequences LLM and tool interactions.
- Modular tool design: each tool lives in its own subpackage, making it easy to add/remove.
- Containerized microservices: clear separation between UI (Node.js) and AI backend (Python).
- Environment-driven configuration: all API keys and ports loaded from .env via docker-compose.

d. Key technologies/frameworks
- Frontend: Next.js 14 (app dir, Server Components), React, TypeScript, Tailwind CSS
- Backend: Python 3.x, LangChain agents, Vercel AI SDK, FastAPI-style server (server.py)
- Deployment/dev: Docker, Docker Compose, Makefile & helper scripts for linting

##### Final checklist
- All components clearly labeled
- Notes or legends explaining any abstractions (e.g., “Agent Chain = chain.py + chat_types.py”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    Browser["User Browser"]:::frontend

    subgraph "Docker Compose"
        direction TB

        subgraph "Frontend Container"
            direction TB
            Layout["layout.tsx"]:::frontend
            Page["page.tsx"]:::frontend
            Globals["globals.css"]:::frontend
            AgentUI["agent.tsx"]:::frontend
            MessageUI["message.tsx"]:::frontend
            SharedUI["shared.tsx"]:::frontend
            UIComponents["components/ui/*"]:::frontend
            PrebuiltVis["components/prebuilt/*"]:::frontend
            Mui["lib/mui.ts"]:::frontend
            UtilsLib["lib/utils.ts"]:::frontend
            ClientUtils["utils/client.tsx"]:::frontend
            ServerUtils["utils/server.tsx"]:::frontend
            Config["Build & Config Files"]:::frontend
        end

        subgraph "Backend Container"
            direction TB
            HTTPServer["server.py"]:::backend
            HotReload["hot_reload.py"]:::backend

            subgraph "Agent Core"
                direction TB
                Chain["chain.py"]:::backend
                ChatTypes["chat_types.py"]:::backend
                Graph["graph.py"]:::backend
            end

            subgraph "Tools Layer"
                direction TB
                FinSearchTool["tools/financials/search/tool.py"]:::backend
                FinSearchSchema["tools/financials/search/schema.py"]:::backend
                InsiderTool["tools/insider_transactions/tool.py"]:::backend
                InsiderSchema["tools/insider_transactions/schema.py"]:::backend
                PricesTool["tools/prices.py"]:::backend
                WebSearchTool["tools/web_search/tavily/tool.py"]:::backend
                WebSearchSchema["tools/web_search/tavily/schema.py"]:::backend
            end
        end
    end

    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        FinancialAPI["Financialdatasets.ai API"]:::external
        Tavily["Tavily Search API"]:::external
    end

    Browser -->|"HTTPS"| Layout
    Layout -->|"Renders page"| Page
    Page -->|"POST /api/chat"| HTTPServer
    HTTPServer -->|"orchestrates"| Chain
    Chain -->|"uses types"| ChatTypes
    Chain -->|"builds graph"| Graph
    Chain -->|"calls"| FinSearchTool
    Chain -->|"calls"| InsiderTool
    Chain -->|"calls"| PricesTool
    Chain -->|"calls"| WebSearchTool
    FinSearchTool -->|"REST/JSON"| FinancialAPI
    InsiderTool -->|"REST/JSON"| FinancialAPI
    PricesTool -->|"REST/JSON"| FinancialAPI
    WebSearchTool -->|"REST/JSON"| Tavily
    Chain -->|"invokes LLM"| OpenAI
    Chain -->|"returns JSON"| HTTPServer
    HTTPServer -->|"JSON payload"| Page
    Page -->|"renders UI components"| SharedUI

    click Layout "https://github.com/virattt/financial-agent-ui/blob/main/frontend/app/layout.tsx"
    click Page "https://github.com/virattt/financial-agent-ui/blob/main/frontend/app/page.tsx"
    click Globals "https://github.com/virattt/financial-agent-ui/blob/main/frontend/app/globals.css"
    click AgentUI "https://github.com/virattt/financial-agent-ui/blob/main/frontend/app/ai/agent.tsx"
    click MessageUI "https://github.com/virattt/financial-agent-ui/blob/main/frontend/app/ai/message.tsx"
    click SharedUI "https://github.com/virattt/financial-agent-ui/blob/main/frontend/app/shared.tsx"
    click UIComponents "https://github.com/virattt/financial-agent-ui/tree/main/frontend/components/ui"
    click PrebuiltVis "https://github.com/virattt/financial-agent-ui/tree/main/frontend/components/prebuilt"
    click Mui "https://github.com/virattt/financial-agent-ui/blob/main/frontend/lib/mui.ts"
    click UtilsLib "https://github.com/virattt/financial-agent-ui/blob/main/frontend/lib/utils.ts"
    click ClientUtils "https://github.com/virattt/financial-agent-ui/blob/main/frontend/utils/client.tsx"
    click ServerUtils "https://github.com/virattt/financial-agent-ui/blob/main/frontend/utils/server.tsx"
    click HTTPServer "https://github.com/virattt/financial-agent-ui/blob/main/backend/gen_ui_backend/server.py"
    click HotReload "https://github.com/virattt/financial-agent-ui/blob/main/backend/hot_reload.py"
    click Chain "https://github.com/virattt/financial-agent-ui/blob/main/backend/gen_ui_backend/chain.py"
    click ChatTypes "https://github.com/virattt/financial-agent-ui/blob/main/backend/gen_ui_backend/chat_types.py"
    click Graph "https://github.com/virattt/financial-agent-ui/blob/main/backend/gen_ui_backend/graph.py"
    click FinSearchTool "https://github.com/virattt/financial-agent-ui/blob/main/backend/gen_ui_backend/tools/financials/search/tool.py"
    click FinSearchSchema "https://github.com/virattt/financial-agent-ui/blob/main/backend/gen_ui_backend/tools/financials/search/schema.py"
    click InsiderTool "https://github.com/virattt/financial-agent-ui/blob/main/backend/gen_ui_backend/tools/insider_transactions/tool.py"
    click InsiderSchema "https://github.com/virattt/financial-agent-ui/blob/main/backend/gen_ui_backend/tools/insider_transactions/schema.py"
    click PricesTool "https://github.com/virattt/financial-agent-ui/blob/main/backend/gen_ui_backend/tools/prices.py"
    click WebSearchTool "https://github.com/virattt/financial-agent-ui/blob/main/backend/gen_ui_backend/tools/web_search/tavily/tool.py"
    click WebSearchSchema "https://github.com/virattt/financial-agent-ui/blob/main/backend/gen_ui_backend/tools/web_search/tavily/schema.py"

    classDef frontend fill:#E0F7FA,stroke:#0288D1,color:#01579B;
    classDef backend fill:#C8E6C9,stroke:#388E3C,color:#1B5E20;
    classDef external fill:#CFD8DC,stroke:#455A64,color:#263238;
```
