How topmate-io/top-chat works
Project Type & Purpose
• This is a full-stack, AI-powered chat interface built with Next.js (App Router) and Vercel AI SDK.
• It combines a React/Next.js frontend, Next.js API routes (backend), a PostgreSQL database, an optional custom MCP server, and integrations with external LLM providers and OAuth services.
Top-Level Architectural Zones
a. Client (Browser & Static Assets)
b. App Server (Next.js)
c. Infrastructure & External Services
Main Components
a. Client Layer
• Browser UI
• React components in src/app and src/components (chat UI, popups, tool selectors, voice, etc.)
• Global CSS, public assets (sounds), localization JSON (messages/).
• Client-side store (Zustand in src/app/store.ts)
• Hook modules (src/hooks/)
b. App Server Layer
• Next.js App Router & API Routes (src/app/api/)
• Authentication middleware & Better Auth integration (src/lib/auth/, middleware.ts)
• Business logic modules (src/lib/):
• AI orchestrator and MCP manager (src/lib/ai/mcp/, create-mcp-client, config storage)
• LLM prompts & speech modules (src/lib/ai/models.ts, speech/openai)
• Cache layer (memory + optional Redis)
• DB access via Drizzle ORM & custom repositories (src/lib/db/pg/, src/lib/db/repository.ts)
• Utility libraries (utils, logger, load-env)
• Scripts & tooling (scripts/, drizzle.config.ts, .husky hooks)
• Dockerfile & compose.yml to containerize the app + Postgres + (optionally) custom-mcp-server
c. Infrastructure & External Services
• PostgreSQL (HOST: POSTGRES_URL)
• Optional custom MCP server (custom-mcp-server/index.ts)
• External AI Providers: OpenAI, Anthropic, Google Generative AI, etc.
• OAuth Providers: Google, GitHub
• (Optional) Redis for caching
• Vercel hosting or local Docker Compose
Interactions & Data Flow
1. User → Browser UI (React pages)
2. UI → Next.js API routes (REST/JSON calls)
3. API routes → Auth module → Token/session store
4. API routes → DB layer for user, thread, chat history
5. API routes → Cache layer (memory or Redis)
6. Chat endpoints → AI orchestrator/MCP manager → calls to external LLMs or MCP servers
7. Responses propagate back to the browser store → UI updates
Architectural Patterns & Principles
• App Router with separation of “(auth)” and “(chat)” segments
• React Server Components + Client Components
• Layered application: UI / API / Business Logic / Persistence
• Adapter pattern for external tools (MCP clients, AI providers, cache, DB)
• Configuration via environment variables and Drizzle config
Technologies & Frameworks
• Next.js (App Router)
• Vercel AI SDK
• React + Zustand store
• Drizzle ORM + PostgreSQL
• Better Auth (session management)
• Node.js + TypeScript
• Docker & Docker Compose
• Optional Redis cache
• Vercel / Playwright integration examples
Layer-Specific Advice
• Frontend: Highlight the App Router structure ((auth), (chat)) and major UI components (chat window, tool dropdown, voice UI).
• Backend: Show API route hierarchy under /api/* and connect them to their respective lib modules (chat, mcp, user/preferences).
• External Integrations: Illustrate calls to AI provider endpoints, MCP server endpoints, OAuth flows, and DB migrations via scripts.
Detail Granularity
• Do not omit the caching layer or the custom MCP server (even if optional).
• Both code modules (TypeScript files/folders) and runtime services (Docker containers).