# wingleeio/chat-zeron architecture

> Architecture diagram of the GitHub repository wingleeio/chat-zeron, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wingleeio/chat-zeron
- Repository: https://github.com/wingleeio/chat-zeron

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        SSR["SSR Entrypoint"]:::frontend
        Client["Client Entrypoint"]:::frontend
        Router["Router & Route Definitions"]:::frontend
        ChatUI["Chat UI Components"]:::frontend
        Form["Form Components"]:::frontend
        UI["Shared UI Elements"]:::frontend
        Icons["Icon Components"]:::frontend
        Hooks["Data Fetching & State Hooks"]:::frontend
        EnvClient["env.client.ts"]:::frontend
        EnvServer["env.server.ts"]:::frontend
        Stores["TanStack Stores"]:::frontend
        Utils["Utils & Constants"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Convex)"
        direction TB
        subgraph "Configuration"
            ConvexConfig["convex.config.ts"]:::backend
            AuthConfig["auth.config.ts"]:::backend
            CORS["cors.ts"]:::backend
        end
        subgraph "Authentication"
            AuthLogic["convex/auth.ts"]:::backend
        end
        subgraph "Database Schema & Models"
            Schema["schema.ts"]:::database
            Models["models.ts"]:::database
            Migrations["migrations.ts"]:::database
            GenTypes["_generated/"]:::database
        end
        subgraph "Serverless Functions"
            direction TB
            ChatLogic["chats.ts\nmessages.ts"]:::backend
            UserMgmt["users.ts"]:::backend
            FileHandling["files.ts\nr2.ts"]:::backend
            StreamingAPI["streaming.ts"]:::backend
            HTTPEndpts["http.ts"]:::backend
            CronJobs["crons.ts"]:::backend
            InitScripts["init.ts"]:::backend
        end
        subgraph "AI Integrations"
            direction TB
            PromptAdapter["ai/prompt.ts"]:::backend
            ProviderAdapter["ai/provider.ts"]:::backend
            ResearchTool["ai/research.ts"]:::backend
            AISchema["ai/schema.ts"]:::backend
            AITools["ai/tools.ts"]:::backend
        end
        TogetherAI["together.ts"]:::backend
        Validators["validators/chat.ts"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI/Anthropic/Gemini\n(Vercel AI SDK)"]:::external
        ExaAI["Exa AI Search"]:::external
        TogetherExt["Together AI Image Gen"]:::external
        R2Storage["Convex R2 / Object Storage"]:::external
    end

    %% Data Store
    ConvexDB["Convex Datastore"]:::database

    %% Connections
    User["User"]:::actor
    User -->|"Initial Request"| SSR
    User -->|"Interaction"| Client

    SSR -->|"hydration & SSR data"| Router
    Client -->|"routing"| Router

    Router -->|"calls Convex Client API"| ConvexConfig
    Router -->|"calls Convex Client API"| AuthLogic

    Client -->|"invoke functions"| ChatLogic
    Client -->|"invoke functions"| UserMgmt
    Client -->|"invoke functions"| FileHandling
    Client -->|"invoke functions"| StreamingAPI
    Client -->|"invoke functions"| HTTPEndpts

    ChatLogic -->|"read/write"| ConvexDB
    UserMgmt -->|"read/write"| ConvexDB
    FileHandling -->|"upload/download"| R2Storage
    StreamingAPI -->|"stream chunks"| ConvexDB
    HTTPEndpts -->|"serve HTTP"| User
    CronJobs -->|"scheduled updates"| ConvexDB
    InitScripts -->|"setup"| ConvexDB

    ChatLogic -->|"call"| PromptAdapter
    ChatLogic -->|"call"| ProviderAdapter
    ResearchTool -->|"search"| ExaAI
    ProviderAdapter -->|"call"| OpenAI
    TogetherAI -->|"image gen"| TogetherExt

    StreamingAPI -->|"stream"| ChatUI

    %% Styling
    classDef frontend fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1
    classDef backend fill:#FCE4EC,stroke:#D81B60,color:#880E4F
    classDef database fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef external fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef actor fill:#FFFFFF,stroke:#000000,color:#000000,stroke-dasharray: 5 5

    %% Click Events
    click SSR "https://github.com/wingleeio/chat-zeron/blob/main/src/ssr.tsx"
    click Client "https://github.com/wingleeio/chat-zeron/blob/main/src/client.tsx"
    click Router "https://github.com/wingleeio/chat-zeron/blob/main/src/router.tsx"
    click Router "https://github.com/wingleeio/chat-zeron/blob/main/src/routeTree.gen.ts"
    click Router "https://github.com/wingleeio/chat-zeron/tree/main/src/routes/"
    click ChatUI "https://github.com/wingleeio/chat-zeron/tree/main/src/components/chat/"
    click Form "https://github.com/wingleeio/chat-zeron/tree/main/src/components/form/"
    click UI "https://github.com/wingleeio/chat-zeron/tree/main/src/components/ui/"
    click Icons "https://github.com/wingleeio/chat-zeron/tree/main/src/components/icons/"
    click Hooks "https://github.com/wingleeio/chat-zeron/tree/main/src/hooks/"
    click EnvClient "https://github.com/wingleeio/chat-zeron/blob/main/src/env.client.ts"
    click EnvServer "https://github.com/wingleeio/chat-zeron/blob/main/src/env.server.ts"
    click Stores "https://github.com/wingleeio/chat-zeron/tree/main/src/stores/"
    click Utils "https://github.com/wingleeio/chat-zeron/blob/main/src/lib/utils.ts"
    click Utils "https://github.com/wingleeio/chat-zeron/blob/main/src/lib/constants.ts"
    click ConvexConfig "https://github.com/wingleeio/chat-zeron/blob/main/convex/convex.config.ts"
    click AuthConfig "https://github.com/wingleeio/chat-zeron/blob/main/convex/auth.config.ts"
    click CORS "https://github.com/wingleeio/chat-zeron/blob/main/convex/cors.ts"
    click AuthLogic "https://github.com/wingleeio/chat-zeron/blob/main/convex/auth.ts"
    click Schema "https://github.com/wingleeio/chat-zeron/blob/main/convex/schema.ts"
    click Models "https://github.com/wingleeio/chat-zeron/blob/main/convex/models.ts"
    click Migrations "https://github.com/wingleeio/chat-zeron/blob/main/convex/migrations.ts"
    click GenTypes "https://github.com/wingleeio/chat-zeron/tree/main/convex/_generated/"
    click ChatLogic "https://github.com/wingleeio/chat-zeron/blob/main/convex/chats.ts"
    click ChatLogic "https://github.com/wingleeio/chat-zeron/blob/main/convex/messages.ts"
    click UserMgmt "https://github.com/wingleeio/chat-zeron/blob/main/convex/users.ts"
    click FileHandling "https://github.com/wingleeio/chat-zeron/blob/main/convex/files.ts"
    click FileHandling "https://github.com/wingleeio/chat-zeron/blob/main/convex/r2.ts"
    click StreamingAPI "https://github.com/wingleeio/chat-zeron/blob/main/convex/streaming.ts"
    click HTTPEndpts "https://github.com/wingleeio/chat-zeron/blob/main/convex/http.ts"
    click CronJobs "https://github.com/wingleeio/chat-zeron/blob/main/convex/crons.ts"
    click InitScripts "https://github.com/wingleeio/chat-zeron/blob/main/convex/init.ts"
    click PromptAdapter "https://github.com/wingleeio/chat-zeron/blob/main/convex/ai/prompt.ts"
    click ProviderAdapter "https://github.com/wingleeio/chat-zeron/blob/main/convex/ai/provider.ts"
    click ResearchTool "https://github.com/wingleeio/chat-zeron/blob/main/convex/ai/research.ts"
    click AISchema "https://github.com/wingleeio/chat-zeron/blob/main/convex/ai/schema.ts"
    click AITools "https://github.com/wingleeio/chat-zeron/blob/main/convex/ai/tools.ts"
    click TogetherAI "https://github.com/wingleeio/chat-zeron/blob/main/convex/together.ts"
    click Validators "https://github.com/wingleeio/chat-zeron/blob/main/convex/validators/chat.ts"
```
