# eccb7/ai-financial-agent architecture

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

- Interactive diagram: https://gitdiagram.com/eccb7/ai-financial-agent
- Repository: https://github.com/eccb7/ai-financial-agent

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB
    %% Presentation Tier
    subgraph "Presentation Tier"
        direction TB
        Browser["User Browser"]:::ui
        AuthUI["Authentication UI\\n(app/(auth))"]:::ui
        ChatUI["Chat UI\\n(app/(chat))"]:::ui
        Components["Reusable UI Components\\n(components/)"]:::ui
        Hooks["Custom React Hooks\\n(hooks/)"]:::ui
    end

    %% Application Tier
    subgraph "Application Tier"
        direction TB
        NextAuthAPI["NextAuth API Routes"]:::server
        ChatAPIs["Chat API Routes"]:::server
        AutoLoginAPI["Auto-login API\\n(app/api/auth/auto-login)"]:::server

        subgraph "Business Logic Layer"
            direction TB
            AILayer["AI Logic\\n(lib/ai)"]:::server
            APILayer["Financial Data API Wrappers\\n(lib/api)"]:::server
            DBLayer["Database Layer\\n(lib/db)"]:::server
            EditorLayer["Editor Logic\\n(lib/editor)"]:::server
        end
    end

    %% Data Tier
    subgraph "Data & External Services"
        direction TB
        Postgres["Postgres DB"]:::db
        OpenAI["OpenAI API"]:::ext
        FinData["Financial Data API"]:::ext
        LangSmith["LangSmith Tracing"]:::ext
    end

    %% Presentation to Application
    Browser -->|"loads UI"| AuthUI
    Browser -->|"loads UI"| ChatUI
    AuthUI -->|"HTTP request"| NextAuthAPI
    ChatUI -->|"HTTP request"| ChatAPIs
    ChatUI -->|"HTTP request"| AutoLoginAPI
    Components --> AuthUI
    Components --> ChatUI
    Hooks --> AuthUI
    Hooks --> ChatUI

    %% Application internal flows
    NextAuthAPI -->|"SQL query"| DBLayer
    AutoLoginAPI --> NextAuthAPI

    ChatAPIs -->|"assemble prompt"| AILayer
    ChatAPIs -->|"fetch market data"| APILayer
    ChatAPIs -->|"read/write history"| DBLayer
    ChatAPIs -->|"editor features"| EditorLayer

    %% Business Logic to External/Data
    AILayer -->|"LLM prompt/response"| OpenAI
    AILayer -->|"trace data"| LangSmith
    APILayer -->|"REST/JSON"| FinData
    DBLayer -->|"SQL query"| Postgres

    %% Return flows
    OpenAI --> AILayer
    FinData --> APILayer
    Postgres --> DBLayer
    DBLayer --> ChatAPIs
    AILayer --> ChatAPIs
    APILayer --> ChatAPIs
    ChatAPIs -->|"HTTP response"| ChatUI
    NextAuthAPI -->|"HTTP response"| AuthUI

    %% Click Events
    click AuthUI "https://github.com/eccb7/ai-financial-agent/tree/main/app/(auth)"
    click NextAuthAPI "https://github.com/eccb7/ai-financial-agent/blob/main/app/(auth)/api/auth/[...nextauth]/route.ts"
    click ChatUI "https://github.com/eccb7/ai-financial-agent/tree/main/app/(chat)"
    click ChatAPIs "https://github.com/eccb7/ai-financial-agent/tree/main/app/(chat)/api"
    click AutoLoginAPI "https://github.com/eccb7/ai-financial-agent/tree/main/app/api/auth/auto-login"
    click Components "https://github.com/eccb7/ai-financial-agent/tree/main/components"
    click AILayer "https://github.com/eccb7/ai-financial-agent/tree/main/lib/ai"
    click APILayer "https://github.com/eccb7/ai-financial-agent/tree/main/lib/api"
    click DBLayer "https://github.com/eccb7/ai-financial-agent/tree/main/lib/db"
    click EditorLayer "https://github.com/eccb7/ai-financial-agent/tree/main/lib/editor"
    click Hooks "https://github.com/eccb7/ai-financial-agent/tree/main/hooks"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef server fill:#D0FFD8,stroke:#000,stroke-width:1px
    classDef db fill:#FFE3B3,stroke:#000,stroke-width:1px
    classDef ext fill:#EBD0FF,stroke:#000,stroke-width:1px
```
