How virattt/financial-agent-ui works
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”)