How cgoinglove/better-chatbot works
Project Type and Purpose
• Full-stack web application built on Next.js App Router
• Provides a React-based UI, serverless API routes, Drizzle ORM data layer, and integration with multiple LLMs & tools via the Model Context Protocol (MCP)
Core Architectural Components
a. Client (Browser)
• React/Next.js app running in the browser
• Uses React Server Components & Client Components (src/app, components/)
• Hooks & SWR for client-side data fetching/state (src/hooks)
b. Next.js Server (Node.js Runtime)
• Renders pages, handles API routes under src/app/api
• Business logic in src/lib (auth, ai, workflows, db, file-storage, cache, etc.)
• Authentication via Better-Auth & OAuth connectors (lib/auth + external OAuth providers)
• Drizzle ORM for migrations & queries (drizzle.config.ts + lib/db + migrations)
• File storage abstraction (Vercel Blob / S3 driver in lib/file-storage)
• Optional cache layer (Redis via lib/cache)
c. Database
• PostgreSQL (Docker-compose / external)
• Schema & repositories under lib/db/pg/repositories
d. File Storage
• Vercel Blob (default) or S3
e. External Services & Protocols
• LLM Providers: OpenAI, Anthropic, Google Generative AI, xAI, Ollama, etc. (lib/ai)
• Model Context Protocol (MCP): External MCP servers (custom-mcp-server microservice + any remote MCP servers)
• Web Search: Exa AI (optional)
• Tool Execution: JS/Python code runners (lib/code-runner), data-viz tools (lib/ai/tools/visualization)
• OAuth Providers: GitHub, Google, Microsoft for social sign-in
f. Custom-MCP-Server Microservice
• A small Express/Next microservice (custom-mcp-server/index.ts) to host user-defined MCP tools
Relationships & Data Flow
1. User interacts in the Browser (UI & React components)
→ API calls to Next.js Server via fetch/route handlers (src/app/api/*)
2. Next.js API routes
→ Authentication layer (lib/auth)
→ Business logic (chat, agents, workflows under lib/ai/workflow, lib/ai/agent)
→ Data access via Drizzle ORM → PostgreSQL
→ File uploads/downloads via File-Storage driver → Blob/S3
→ Caching (optional) → Redis
→ External calls to LLM providers & MCP servers (lib/ai & custom-mcp-server)
3. Real-time features (voice chat, streaming responses)
→ SSE/WebSocket-style streaming from Next.js to client
Architectural Patterns & Design Principles
• Monolithic container (Next.js) with serverless function style APIs
• Folder-based routing (App Router) dividing UI, API, and middleware
• Separation of Concerns:
– UI (components/)
– Business Logic (lib/ai, lib/auth, lib/workflow)
– Data Access (lib/db)
– Infrastructure (docker/, scripts/, drizzle migrations)
a. Browser/Client Layer
– React Server/Client Components (src/app, components/)
– Hooks & SWR for data fetching
b. Next.js Server (Single Container)
– App Router & Middleware (src/app/layout.tsx, middleware.ts)
– API Routes (src/app/api/*)
– Business Logic Modules (src/lib/*)
· auth, ai, workflows, file-storage, cache, code-runner
– Drizzle ORM & Migrations (drizzle.config.ts + lib/db)
– File Upload/Download (lib/file-storage)
– Caching Layer (lib/cache → Redis)
– Instrumentation & Logging (src/instrumentation.ts + lib/logger)
c. Custom-MCP-Server Service
– HTTP endpoints (custom-mcp-server/index.ts)
– Manages third-party tool definitions via MCP protocol
d. Data Stores
– PostgreSQL (Docker or external)
– Redis (optional, for rate limiting, ephemeral caching)
– Blob/S3 file storage
e. External Services
– LLM APIs (OpenAI, Claude, Google, xAI, Ollama)
– Exa AI (Web Search)
– OAuth: GitHub, Google, Microsoft