# get-convex/convex-demos architecture

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

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

## Overview

##### Project Type & Purpose
- This is a monorepo of standalone demo applications (“Convex Demos”) illustrating how to build full-stack web apps using Convex as a serverless backend.
- Each demo directory (e.g., args-validation, file-storage, nextjs-app-router, etc.) is a self-contained full-stack project comprised of:
- A frontend (React + Vite or Next.js)
- A backend “convex” folder containing serverless functions, schema definitions, and generated API bindings

##### High-Level File Structure Patterns
For each demo folder (except Next.js apps which follow the Next.js convention):
- index.html – entry point for Vite
- package.json, tsconfig.json, vite.config.mts – build & tooling
- src/ – React application code (App.tsx, main.tsx, CSS, hooks)
- convex/ – backend code
– schema.ts, messages.ts – data model & subscriptions
– *.ts/.js files implementing serverless functions
– _generated/ – code-generated API & dataModel bindings

For Next.js demos:
- app/ or pages/ – Next.js routes & components
- convex/ – same structure as above
- next.config.js, tsconfig.json, package.json

##### Core Architectural Components
A. Frontend Client
– React/Vite or Next.js application
– UI components binding to reactive Convex hooks or fetch calls
B. Convex Serverless Backend
– Convex functions (queries, mutations, cron jobs, auth hooks, etc.)
– Schema + messages defining data model & real-time update channels
– Generated API layer ( _generated/api.js/d.ts )
C. Convex Database & Real-Time Sync
– Automatic storage & caching managed by Convex
– WebSocket or HTTP transport for live updates
D. Build & Deployment
– Vite bundler or Next.js build
– Convex CLI / serverless deploy pipelines (not shown but implied)

##### Relationships & Interactions
- The Frontend calls generated API functions, which invoke Convex serverless functions.
- Convex functions read/write from the Convex database; subscriptions push real-time updates back to the client.
- Build tools watch local code, regenerate API bindings, and redeploy serverless functions seamlessly.

##### Architectural Patterns & Principles
- Full-stack separation: clear divide between UI layer and backend functions
- Reactive data flow: UI subscribes to Convex query results, auto-updates on data change
- Code-generation: type-safe API bindings to backend
- Serverless functions: each independent function deployed on demand (includes cron jobs in cron-jobs demo)
- Modular demos: each directory isolates a single use case

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Monorepo: Convex Demos"
        subgraph "args-validation Demo"
            subgraph "Frontend Client" 
                EntryHTML["index.html"]:::frontend
                MainTSX["main.tsx"]:::frontend
                AppTSX["App.tsx"]:::frontend
                StylesCSS["index.css"]:::frontend
            end

            subgraph "Convex API Layer"
                API_JS["api.js"]:::api
                API_DTS["api.d.ts"]:::api
                DATAMODEL["dataModel.d.ts"]:::api
            end

            Runtime["Convex Serverless Runtime\nmessages.ts"]:::backend
            Storage["Convex Storage\n(Realtime DB)"]:::storage

            subgraph "Build & Tooling"
                ViteConfig["vite.config.mts"]:::tooling
                TSConfig["tsconfig.json"]:::tooling
                PackageJSON["package.json"]:::tooling
            end
        end
    end

    AppTSX -->|"calls API"| API_JS
    API_JS -->|"queries/mutations"| Runtime
    Runtime -->|"read/write"| Storage
    Storage -->|"push updates"| AppTSX

    click EntryHTML "https://github.com/get-convex/convex-demos/blob/main/args-validation/index.html"
    click MainTSX "https://github.com/get-convex/convex-demos/blob/main/args-validation/src/main.tsx"
    click AppTSX "https://github.com/get-convex/convex-demos/blob/main/args-validation/src/App.tsx"
    click StylesCSS "https://github.com/get-convex/convex-demos/blob/main/args-validation/src/index.css"
    click API_JS "https://github.com/get-convex/convex-demos/blob/main/args-validation/convex/_generated/api.js"
    click API_DTS "https://github.com/get-convex/convex-demos/blob/main/args-validation/convex/_generated/api.d.ts"
    click DATAMODEL "https://github.com/get-convex/convex-demos/blob/main/args-validation/convex/_generated/dataModel.d.ts"
    click Runtime "https://github.com/get-convex/convex-demos/blob/main/args-validation/convex/messages.ts"
    click ViteConfig "https://github.com/get-convex/convex-demos/blob/main/args-validation/vite.config.mts"
    click TSConfig "https://github.com/get-convex/convex-demos/blob/main/args-validation/tsconfig.json"
    click PackageJSON "https://github.com/get-convex/convex-demos/blob/main/args-validation/package.json"

    classDef frontend fill:#E0F7FA,stroke:#00838F,color:#006064
    classDef api fill:#BBDEFB,stroke:#1976D2,color:#0D47A1
    classDef backend fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef storage fill:#CFD8DC,stroke:#455A64,color:#263238
    classDef tooling fill:#F0F4C3,stroke:#827717,color:#33691E
```
