spb/vquant Public MIT
VibeQuant — AI-powered institutional-grade financial intelligence platform.
TypeScript 84.3%
Python 11.7%
JavaScript 1.6%
CSS 1.5%
HTML 0.7%
1<!--2 =============================================================================3 VibeQuant (vquant) — AI-Powered Financial Intelligence Platform4 -----------------------------------------------------------------------------5 File: docs/ARCHITECTURE.md67 Author: Simon-Pierre Boucher8 Contact: contact@spboucher.ai9 Website: https://www.spboucher.ai10 Demo: https://www.vquant.ai11 License: MIT (see LICENSE)1213 Copyright © 2026 Simon-Pierre Boucher. All rights reserved.14 =============================================================================15-->1617# Architecture1819Detailed technical architecture of the VibeQuant platform.2021## System Overview2223```24┌──────────────────────────────────────────────────────────────────┐25│ CLIENT (React 18) │26│ ┌──────────┐ ┌──────────────┐ ┌────────────┐ ┌───────────┐ │27│ │ Chat UI │ │ Explore Page │ │ Admin Panel│ │ Auth/Docs │ │28│ │ (SSE) │ │ (FMP data) │ │ (Analytics)│ │ (Sessions)│ │29│ └────┬─────┘ └──────┬───────┘ └─────┬──────┘ └─────┬─────┘ │30│ │ │ │ │ │31│ ┌────┴───────────────┴────────────────┴───────────────┴─────┐ │32│ │ TanStack Query + useChatSession Hook │ │33│ └───────────────────────────┬───────────────────────────────┘ │34└──────────────────────────────┼──────────────────────────────────┘35 │ HTTP / SSE36┌──────────────────────────────┼──────────────────────────────────┐37│ SERVER (Express 4) │38│ ┌───────────────────────────┴───────────────────────────────┐ │39│ │ Route Modules (6) │ │40│ │ auth │ admin │ analytics │ fmp │ reports │ chat (SSE) │ │41│ └───┬───────┬──────────┬──────────┬──────────┬──────────────┘ │42│ │ │ │ │ │ │43│ ┌───┴───┐ ┌─┴──────┐ ┌┴────────┐ │ ┌─────┴──────────────┐ │44│ │Storage│ │Analytics│ │Zod Valid│ │ │ Claude Opus 4.8 │ │45│ │(Drizzle)│ │Metrics │ │Schemas │ │ │ 237 tools │ │46│ └───┬───┘ └────────┘ └────────┘ │ │ 5-tool batching │ │47│ │ │ └──────────┬──────────┘ │48│ ┌───┴──────┐ ┌─────┴──────┐ ┌─────┴──────────┐ │49│ │SQLite/PG │ │ FMP Service│ │ Python Engine │ │50│ │(Drizzle) │ │ 256 funcs │ │ 17 libraries │ │51│ └──────────┘ └────────────┘ └────────────────┘ │52│ │53│ ┌────────────────────────────────────────────────────────────┐ │54│ │ External APIs │ │55│ │ Tavily │ Firecrawl │ Exa │ SerpAPI │ ElevenLabs │ │56│ └────────────────────────────────────────────────────────────┘ │57└─────────────────────────────────────────────────────────────────┘58```5960## Directory Structure6162```63vquant/64├── client/src/ # Frontend65│ ├── App.tsx # Router + ErrorBoundary + providers66│ ├── main.tsx # Entry point (createRoot)67│ ├── config.ts # App config, endpoints, feature flags68│ ├── index.css # Global styles + Tailwind69│ │70│ ├── components/71│ │ ├── chat/ # 13 chat-specific components72│ │ │ ├── search-bar.tsx # Query input with image upload73│ │ │ ├── streaming-answer.tsx # Real-time markdown rendering74│ │ │ ├── agent-steps.tsx # Tool execution progress display75│ │ │ ├── tool-results.tsx # Financial data cards76│ │ │ ├── monte-carlo-results.tsx # Monte Carlo visualization77│ │ │ ├── custom-python-figure.tsx # Python-generated chart gallery78│ │ │ ├── result-card.tsx # Web search result card79│ │ │ ├── search-bar.tsx # Search input component80│ │ │ ├── searching-widget.tsx # Loading animation81│ │ │ ├── empty-state.tsx # Welcome screen with suggestions82│ │ │ ├── error-state.tsx # Error display with retry83│ │ │ ├── conversation-history.tsx # Past Q&A accordion84│ │ │ ├── session-history.tsx # Session list sidebar85│ │ │ ├── share-button.tsx # Report sharing dialog86│ │ │ └── download-buttons.tsx # PDF/DOCX export buttons87│ │ ├── explore/ # 7 stock explorer components88│ │ │ ├── stock-header.tsx # Symbol + price display89│ │ │ ├── market-overview.tsx # Gainers, losers, actives90│ │ │ ├── financial-statements-view.tsx91│ │ │ ├── metrics-view.tsx92│ │ │ ├── analyst-view.tsx93│ │ │ ├── news-view.tsx94│ │ │ └── ownership-view.tsx95│ │ ├── financial/ # Charts96│ │ │ ├── advanced-price-chart.tsx # TradingView-style chart97│ │ │ └── options-pricing-card.tsx # Black-Scholes display98│ │ ├── ui/ # 35 shadcn/ui primitives99│ │ ├── error-boundary.tsx # Global React error handler100│ │ ├── streaming-answer.tsx # Shared markdown renderer101│ │ ├── market-ticker.tsx # Top market ticker bar102│ │ ├── theme-provider.tsx # Dark/light mode context103│ │ ├── theme-toggle.tsx # Theme switch button104│ │ └── theme-color-picker.tsx # Accent color selector105│ │106│ ├── hooks/107│ │ ├── useChatSession.ts # All chat state + business logic (313 lines)108│ │ ├── useChatMutation.ts # SSE streaming fetch client109│ │ ├── useAnalytics.ts # Heartbeat tracking110│ │ ├── use-toast.ts # Toast notifications111│ │ └── use-mobile.tsx # Responsive media query112│ │113│ ├── pages/ # 9 route pages114│ │ ├── home.tsx # Main chat (255 lines, pure render)115│ │ ├── explore.tsx # Stock explorer116│ │ ├── admin.tsx # Admin dashboard117│ │ ├── auth.tsx # Login / register118│ │ ├── showcase.tsx # Community shared reports119│ │ ├── shared-report.tsx # View shared report120│ │ ├── documentation.tsx # Docs page121│ │ ├── slides-generator.tsx # Beamer slide creator122│ │ ├── privacy.tsx / terms.tsx # Legal pages123│ │ └── not-found.tsx # 404124│ │125│ ├── lib/126│ │ ├── queryClient.ts # TanStack Query defaults127│ │ └── utils.ts # cn() class merger128│ │129│ └── utils/130│ ├── chartCapture.ts # DOM-to-image for charts131│ └── pdfGenerator.ts # Client-side PDF assembly132│133├── server/ # Backend134│ ├── index.ts # Express bootstrap, CORS, sessions, middleware135│ ├── routes.ts # /api/chat (SSE) + /api/speech-to-text (~1960 lines)136│ ├── routes/137│ │ ├── auth.ts # /api/auth/* (4 endpoints)138│ │ ├── admin.ts # /api/admin/* (5 endpoints) + requireAdmin139│ │ ├── analytics.ts # /api/analytics/* (4 endpoints)140│ │ ├── fmp.ts # /api/fmp/* (23 endpoints)141│ │ ├── reports.ts # /api/share, sessions, docs, download (8 endpoints)142│ │ └── validation.ts # Zod request schemas143│ ├── services/144│ │ ├── claude/145│ │ │ ├── toolDefinitions.ts # 237 tool definitions (~4,480 lines)146│ │ │ └── tokenManagement.ts # Context window management147│ │ ├── claudeService.ts # Claude API streaming integration148│ │ ├── fmpService.ts # 256 FMP API wrapper functions149│ │ ├── python/150│ │ │ ├── monteCarlo.ts # Monte Carlo simulation executor151│ │ │ ├── optionsPricing.ts # Black-Scholes executor152│ │ │ ├── garch.ts # GARCH model executor153│ │ │ ├── var.ts # VaR + portfolio + risk + plot + custom Python154│ │ │ ├── shared.ts # Python path config155│ │ │ └── index.ts # Barrel exports156│ │ ├── pythonExecutor.ts # Re-exports from python/157│ │ ├── firecrawlService.ts # 7 Firecrawl functions158│ │ ├── tavilyService.ts # 6 Tavily functions159│ │ ├── exaService.ts # 2 Exa functions160│ │ ├── serpapiService.ts # 11 SerpAPI functions161│ │ ├── pdfService.ts # Puppeteer PDF + Pandoc DOCX162│ │ ├── beamerSlidesService.ts # LaTeX Beamer slides163│ │ ├── slidesConverterService.ts # Markdown to slide structure164│ │ ├── contentSummarizerService.ts # Content summarization165│ │ ├── financialDataService.ts # Options chain data166│ │ └── *.py # 11 Python services167│ ├── db.ts # Drizzle ORM setup (SQLite + PostgreSQL)168│ ├── storage.ts # Typed data access layer (IStorage interface)169│ ├── types/modules.d.ts # Module declarations170│ └── utils/logger.ts # Structured logging utility171│172├── shared/ # Shared between client & server173│ ├── schema.ts # PostgreSQL schema (Drizzle, 9 tables)174│ ├── schema-sqlite.ts # SQLite schema (Drizzle, 9 tables)175│ └── types.ts # API interfaces (SearchResult, ChatRequest, etc.)176│177├── docs/ # Documentation178├── .github/workflows/ci.yml # CI pipeline179├── vitest.config.ts # Test config180├── eslint.config.js # ESLint flat config181├── vite.config.ts # Vite build config182├── tsconfig.json # TypeScript config183├── tailwind.config.ts # Tailwind config184├── .prettierrc # Prettier config185├── .editorconfig # Editor config186├── .env.example # Env template187└── .gitignore # Git ignore rules188```189190## Data Flow191192### Chat Request Flow193194```195User types query196 → useChatSession.handleSearch()197 → useChatMutation.mutate() (POST /api/chat)198 → Express receives request199 → Zod validates chatBodySchema200 → SSE headers sent, streaming begins201 → Claude Opus 4.8 called with 237 tools202 → Claude returns tool_use blocks203 → Tools executed in batches of 5204 → FMP API calls (financial data)205 → Python scripts (quant analysis)206 → Web search (Tavily/Firecrawl/Exa)207 → Results sent back to Claude208 → Claude generates final answer209 → Answer streamed via SSE events:210 - type: "text" (incremental tokens)211 - type: "sources" (web results)212 - type: "tool_start/complete/error"213 - type: "tool_result" (data display)214 - type: "custom_python_figures"215 - type: "done" (sessionId)216 → Client renders in real-time217 → Session saved to database218```219220### Database Architecture221222```223users ──┐224 ├── conversationSessions (userId FK)225 ├── activeUsers (userId FK)226 └── requestLogs (userId FK)227228crawledPages ── embeddings (pageId FK)229230messages (sessionId, no FK)231sharedReports (standalone)232analyticsMetrics (standalone, time-series)233```234235## Key Design Decisions236237| Decision | Choice | Rationale |238|----------|--------|-----------|239| **Database** | SQLite (dev) / PostgreSQL (prod) | Zero setup locally, Neon serverless for production |240| **ORM** | Drizzle | Type-safe, lightweight, dual-driver support |241| **Streaming** | Server-Sent Events | Simpler than WebSocket for unidirectional streaming |242| **State management** | TanStack Query + hooks | No Redux needed — server state cached, local state in hooks |243| **UI framework** | shadcn/ui + Radix | Accessible primitives, full control over styling |244| **Validation** | Zod | Runtime validation matching TypeScript types |245| **AI model** | Claude Fable 5 (+ 5 selectable models) | up to 1M token context for complex financial analysis |246| **Python execution** | Child process spawn | Isolated execution, no shared state, timeout support |247