# get-convex/agent architecture

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

- Interactive diagram: https://gitdiagram.com/get-convex/agent
- Repository: https://github.com/get-convex/agent

## Overview

##### Project Type and Purpose
- This is a TypeScript-based library package (“@convex-dev/agent”) for building AI-driven agents on top of the Convex platform.
- It provides client-side components (in both raw client and React flavors), serverless Convex functions (the “agent workflows”), and examples/playground frontends demonstrating how to wire everything together.

##### High-Level Architectural Overview
Break the system into these primary layers:
A. Frontend UIs
- “example/ui” (React + Vite/Tailwind)
- “playground/src” (full demo app with UI components, context editors, etc.)
B. Client-Side Library
- src/client: low-level API wrappers (thread/message management, streaming, file operations)
- src/react: React hooks & utilities for optimistic updates, streaming deltas, UI message conversion
C. Convex Backend
- example/convex: serverless functions (agents, threads, messages, files, RAG, rate-limiting, usage tracking, workflows)
- src/component: the core “component” code (schema, business logic, streams, threads, tools)
D. Persistence & Services
- Convex database (threads, messages, vectors for RAG, file metadata)
- File storage (for uploaded/generated files)
- External LLM providers (OpenAI, Anthropic, etc.)
- Optional external services (vector stores, other APIs when used as Tools)

##### Component Relationships & Data Flow
1. User interacts with Frontend UI →
2. UI calls React hooks (src/react) or raw client APIs (src/client) →
3. Client library issues streaming RPCs / function calls to Convex Backend →
4. Convex server functions execute:
a. Manage convo context (threads/messages) in Convex DB
b. Optionally perform RAG/vector search
c. Call out to LLM provider or user-supplied Tools
d. Persist results, update threads/messages, handle rate-limiting & usage tracking
e. Stream deltified responses back over websockets
5. Client receives and applies deltas → UI re-renders incremental agent output
6. File operations go through file storage and update Convex DB references

##### Key Architectural Patterns & Principles
- **Serverless Functions**: Each agent/workflow step is a stateless Convex function.
- **Event-Driven & Streaming**: Uses websocket-based delta streams for real-time sync.
- **Layered Separation**: Clear boundary between UI, client APIs, backend logic, and persistence.
- **Composable Tools**: Agent workflows call Tools (external or internal Convex functions) via a unified interface.
- **RAG Integration**: Hybrid vector/text search co-located with message context.
- **Cross-Cutting**: Rate limiting and usage tracking as pluggable components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend UI Layer
    subgraph "Frontend UI"
        direction TB
        ExampleUI["Example UI\n(React + Vite/Tailwind)"]:::frontend
        PlaygroundUI["Playground UI\n(Demo App)"]:::frontend
    end

    %% Client Library Layer
    subgraph "Client Library"
        direction TB
        ClientAPI["Low-Level API Wrappers"]:::client
        ClientGen["Generated Client API Types"]:::client
        Streaming["Streaming & Utilities"]:::client
        ClientTestsSetup["setup.test.ts\n(Client API Tests)"]:::client
        ClientTestsIndex["index.test.ts\n(Client API Tests)"]:::client
        ReactHooks["React Hooks & Utilities"]:::client
        ReactDeltasTest["deltas.test.ts\n(React Tests)"]:::client
        ReactToUITest["toUIMessages.test.ts\n(React Tests)"]:::client
        UseSmooth["useSmoothText.ts"]:::client
        OptSend["optimisticallySendMessage.ts"]:::client
        ToUIMsg["toUIMessages.ts"]:::client
    end

    %% Convex Backend Layer
    subgraph "Convex Backend"
        direction TB
        ConvexExample["Example Serverless Functions"]:::backend
        ConvexGen["Generated Server API Types"]:::backend
        Agents["agents"]:::backend
        Chat["chat"]:::backend
        ConvexFiles["files"]:::backend
        Rag["rag"]:::backend
        RateLimit["rate_limiting"]:::backend
        UsageTracking["usage_tracking"]:::backend
        Tools["tools"]:::backend
        Utils["utils.ts"]:::backend
    end

    %% Core Component Code
    subgraph "Core Component Code"
        direction TB
        CoreComp["Component Module"]:::backend
        CoreGen["Generated Component API Types"]:::backend
        Streams["streams.ts"]:::backend
        Threads["threads.ts"]:::backend
        Messages["messages.ts"]:::backend
        CoreFiles["files.ts"]:::backend
        CoreFilesTest["files.test.ts"]:::backend
        Schema["schema.ts"]:::backend
        APIKeys["apiKeys.ts"]:::backend
        Vector["vector"]:::backend
        Users["users.ts"]:::backend
        UsersTest["users.test.ts"]:::backend
    end

    %% Persistence & External Services
    subgraph "Persistence & External"
        direction TB
        DB["Convex DB\n(Threads, Messages, Vectors)"]:::external
        FileStorage["File Storage"]:::external
        LLM["External LLM Providers"]:::external
    end

    %% Relationships
    ExampleUI -->|"use React Hooks"| ReactHooks
    ExampleUI -->|"use Client API"| ClientAPI
    PlaygroundUI -->|"use React Hooks"| ReactHooks
    PlaygroundUI -->|"use Client API"| ClientAPI

    ReactHooks -->|"calls API"| ClientAPI
    ClientAPI -->|"callAgent() RPC"| ConvexExample
    ClientAPI -.->|"streamDelta() WS"| ConvexExample
    ConvexExample -->|"persist/fetch"| DB
    ConvexExample -->|"store files"| FileStorage
    ConvexExample -->|"call LLM"| LLM
    ConvexExample -.->|"stream responses"| ClientAPI
    ClientAPI -->|"receive deltas"| ReactHooks
    ReactHooks -->|"update UI"| ExampleUI

    %% Core component usage
    ConvexExample -->|"imports core component"| CoreComp

    %% Click events
    click ExampleUI "https://github.com/get-convex/agent/tree/main/example/ui"
    click PlaygroundUI "https://github.com/get-convex/agent/tree/main/playground/src"
    click ClientAPI "https://github.com/get-convex/agent/tree/main/src/client"
    click ClientGen "https://github.com/get-convex/agent/tree/main/src/client/_generated"
    click Streaming "https://github.com/get-convex/agent/blob/main/src/client/streaming.ts"
    click ClientTestsSetup "https://github.com/get-convex/agent/blob/main/src/client/setup.test.ts"
    click ClientTestsIndex "https://github.com/get-convex/agent/blob/main/src/client/index.test.ts"
    click ReactHooks "https://github.com/get-convex/agent/tree/main/src/react"
    click ReactDeltasTest "https://github.com/get-convex/agent/blob/main/src/react/deltas.test.ts"
    click ReactToUITest "https://github.com/get-convex/agent/blob/main/src/react/toUIMessages.test.ts"
    click UseSmooth "https://github.com/get-convex/agent/blob/main/src/react/useSmoothText.ts"
    click OptSend "https://github.com/get-convex/agent/blob/main/src/react/optimisticallySendMessage.ts"
    click ToUIMsg "https://github.com/get-convex/agent/blob/main/src/react/toUIMessages.ts"
    click ConvexExample "https://github.com/get-convex/agent/tree/main/example/convex"
    click ConvexGen "https://github.com/get-convex/agent/tree/main/example/convex/_generated"
    click Agents "https://github.com/get-convex/agent/tree/main/example/convex/agents"
    click Chat "https://github.com/get-convex/agent/tree/main/example/convex/chat"
    click ConvexFiles "https://github.com/get-convex/agent/tree/main/example/convex/files"
    click Rag "https://github.com/get-convex/agent/tree/main/example/convex/rag"
    click RateLimit "https://github.com/get-convex/agent/tree/main/example/convex/rate_limiting"
    click UsageTracking "https://github.com/get-convex/agent/tree/main/example/convex/usage_tracking"
    click Tools "https://github.com/get-convex/agent/tree/main/example/convex/tools"
    click Utils "https://github.com/get-convex/agent/blob/main/example/convex/utils.ts"
    click CoreComp "https://github.com/get-convex/agent/tree/main/src/component"
    click CoreGen "https://github.com/get-convex/agent/tree/main/src/component/_generated"
    click Streams "https://github.com/get-convex/agent/blob/main/src/component/streams.ts"
    click Threads "https://github.com/get-convex/agent/blob/main/src/component/threads.ts"
    click Messages "https://github.com/get-convex/agent/blob/main/src/component/messages.ts"
    click CoreFiles "https://github.com/get-convex/agent/blob/main/src/component/files.ts"
    click CoreFilesTest "https://github.com/get-convex/agent/blob/main/src/component/files.test.ts"
    click Schema "https://github.com/get-convex/agent/blob/main/src/component/schema.ts"
    click APIKeys "https://github.com/get-convex/agent/blob/main/src/component/apiKeys.ts"
    click Vector "https://github.com/get-convex/agent/tree/main/src/component/vector"
    click Users "https://github.com/get-convex/agent/blob/main/src/component/users.ts"
    click UsersTest "https://github.com/get-convex/agent/blob/main/src/component/users.test.ts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef client fill:#d4edda,stroke:#333,stroke-width:1px
    classDef backend fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px
```
