How eccb7/ai-financial-agent works
Project type and purpose
• This is a full-stack Next.js 13 “app”-directory web application named “AI Financial Agent.”
• Purpose: Provide an AI-powered chat interface for financial research, stock analysis and data visualization. It uses OpenAI LLMs plus a Financial Datasets API and persists user/chat data in a Postgres database.
File structure
• Top-level Next.js conventions:
• app/ – route handlers and server/client React components, organized into two “route groups”:
– (auth): all authentication UI and NextAuth API routes
– (chat): chat UI, chat history, file uploads, suggestion & voting APIs
• app/api/ – additional open API routes (e.g. auto-login)
• components/ – reusable client UI components (chat bubbles, sidebars, editors, tables, etc.)
• lib/ – business logic broken into subfolders:
• ai/ – OpenAI prompt engineering, model selection, custom middleware
• api/ – wrappers for external data-API calls (stock filters, financial data)
• db/ – Drizzle ORM config, schema, migrations, queries
• editor/, types/, utils/ – custom editor logic, TypeScript types, shared utilities
• hooks/ – custom React hooks
• Configuration files: next.config.ts, drizzle.config.ts, tailwind.config.ts, .env.example, pnpm-lock.yaml
Extract architectural insights from README
• Tech stack: Next.js 13 (React Server Components + Client Components), NextAuth, Drizzle ORM → PostgreSQL, Tailwind CSS
• External services:
• OpenAI API (chat completions)
• Financial Datasets API (real-time & historical market data)
• LangSmith for tracing (optional)
• Deployment: Vercel serverless functions
Main components & their boundaries
A. Client (Browser) – React UI (app/ + components/)
B. Next.js Server (Server Components, API Routes)
1. NextAuth authentication flow
2. Chat APIs: /api/chat, /api/document, /api/files/upload, /api/history, /api/messages/count, /api/suggestions, /api/vote
C. Business Logic Layer (lib/) – orchestrates calls to AI, DB, external APIs
D. Database – PostgreSQL managed via Drizzle ORM
E. External Services – OpenAI, Financial Datasets API, Optional LangSmith
Relationships & interactions
1. User → Browser UI → Next.js pages/components
2. UI calls NextAuth API → validate session → issues JWT/cookie
3. Chat UI triggers fetch→ Next.js API routes
4. API route → calls lib/ai for prompt assembly → calls OpenAI → receives completion
5. API route → calls lib/api for financial data → receives market data
6. API route → persists queries and chat history via lib/db → Postgres
7. API route returns combined data stream → front-end updates UI
Architectural patterns & design principles
• Separation of concerns: UI (components) / Routing (app/) / Business logic (lib/) / Persistence (db/)
• React Server vs Client Components: server renders data-heavy components, client handles interactive state
• API-centric design: discrete serverless functions for each capability
• ORM for type-safe DB access and migrations (Drizzle)
• Layered integration with external AI and data services
Essential elements to capture
• NextAuth authentication sub-system (login, register, session validation)
• Chat operations: streaming AI responses, financial data ingestion, user voting/suggestions
• Database migrations & schema management via Drizzle
• Key third-party integrations: OpenAI, Financial Datasets API, LangSmith tracing