How wingleeio/chat-zeron works
Project Type and Purpose
• Zeron Chat is a full-stack, AI-powered chat application that unifies multiple LLMs (OpenAI, Anthropic, Gemini, etc.) into one interface.
• The front end is built in React/TypeScript with SSR and CSR via TanStack Start. The back end is a serverless platform using Convex for data, functions, and real-time streaming.
• External AI services (Vercel AI SDK, Together AI, Exa AI) and image uploads integrate into the chat flow.
File Structure
• Top-level “public” folder holds static assets (manifest, robots.txt, background, screenshot).
• “src” contains:
• client.tsx, ssr.tsx, router.tsx, route definitions → front-end entry points & routing
• hooks/ (data fetching, user state, chat pagination)
• lib/ (constants, utils)
• env.client.ts / env.server.ts → environment variables for client vs. server
• stores/ (TanStack stores for state)
• “convex” folder contains:
• convex.config.ts, auth.config.ts, cors.ts → Convex setup
• ai/ (prompt building, provider adapters, tool integrations)
• functions.ts, http.ts, chats.ts, messages.ts, users.ts, files.ts, streaming.ts, etc. → server-side resolvers, cron jobs, APIs
• migrations.ts, schema.ts → database model
• _generated/ → auto-generated types & clients
• Config files: package.json, pnpm-lock.yaml, tsconfig.json, .gitignore, .vscode settings.
README for Insights
• Confirms tech stack: React, TypeScript, Vercel AI SDK, Convex.
• Lists features: resumable streams (persistent-text-streaming), fast navigation, search (Exa), research, image gen (Together AI), uploads, branching, sharing, theming.
Main Components & Relationships
a. Components:
• Frontend (React + TanStack Start):
– SSR entrypoint (ssr.tsx)
– Client entrypoint (src/client.tsx)
– Router & routeTree (router.tsx, route definitions)
– UI components & hooks
• Backend (Convex):
– Database (Convex persisted storage)
– Serverless functions (chat logic, streaming, auth, file handling)
– CRON jobs (convex/crons.ts)
– HTTP endpoints (convex/http.ts) for public sharing or integrations
• External Services:
– AI providers (OpenAI, Claude, Gemini via Vercel AI SDK & custom Convex AI tools)
– Search tool (Exa AI)
– Image generation (Together AI)
– Object storage (Convex R2 or other file service)
b. Data Flows & Interactions:
1. User Action in UI → Router dispatch → React component calls Convex client (via src/api.ts).
2. Convex client → Invokes serverless function (e.g., sendMessage, fetchHistory, streamResponse).
3. Serverless function may:
• Read/write to Convex datastore (schema.ts)
• Call external AI SDKs (ai/provider.ts) & return streaming chunks to client
• Trigger CRON or file uploads
4. Streaming responses flow back through Convex streaming API to the client, where UIMessage handles resumable streams.
5. SSR layer fetches initial chat state for the initial HTML render.
c. Architectural Patterns & Principles:
• Single-page application with hybrid SSR/CSR
• Serverless microservices (Convex functions) grouped by domain (chat, users, files, ai)
• Event-driven streaming for AI responses
• Separation of concerns: UI vs. data vs. business logic
d. Key Technologies:
• React + TanStack Start (client & SSR)
• Convex (serverless DB & functions)
• Vercel AI SDK, custom Convex AI tools
• TypeScript end-to-end (with auto-generated types)
• Shadcn/UI for component styling