# thomasballinger/convex-clerk-users-table architecture

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

- Interactive diagram: https://gitdiagram.com/thomasballinger/convex-clerk-users-table
- Repository: https://github.com/thomasballinger/convex-clerk-users-table

## Overview

##### Project Type and Purpose
- This is a full-stack, real-time chat application with user authentication.
- Frontend: React (TSX) + Vite.
- Backend: Convex serverless functions + Convex DB.
- Authentication: Clerk (external service), with webhooks keeping the “users” table in sync.

##### File Structure Analysis
- Top-level “src/”: React components (App.tsx, LoginPage.tsx, SigningUp.tsx), entry point (main.tsx), styling (index.css).
- index.html and vite.config.ts: static shell and build configuration.
- “convex/”:
- schema.ts defines Convex data model (messages, users).
- sendMessage.ts & listMessages.ts: RPC functions for sending/listing chat messages.
- users.ts & http.ts: HTTP handler for Clerk webhooks updating user records.
- auth.config.js: JWT validation config for Convex.
- _generated/: TypeScript definitions for API, server, dataModel.

##### Key Architectural Insights from README
- The frontend uses ClerkProvider (in main.tsx) with a publishable key, obtains JWTs.
- Convex functions authenticate requests using auth.config.js.
- Clerk webhooks post user-lifecycle events to the Convex HTTP endpoint, updating the “users” table.
- Frontend subscribes (via Convex client) to live updates on messages and users.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        direction TB
        A_HTML["index.html"]:::code
        B_Vite["vite.config.ts"]:::code
        C_Main["src/main.tsx"]:::code
        D_App["src/App.tsx"]:::code
        E_Login["src/LoginPage.tsx"]:::code
        F_SignUp["src/SigningUp.tsx"]:::code
        G_Badge["src/Badge.tsx"]:::code
        H_Styles["src/index.css"]:::code
    end

    subgraph "Backend - Convex"
        direction TB
        I_Schema["convex/schema.ts"]:::code
        J_List["convex/listMessages.ts"]:::code
        K_Send["convex/sendMessage.ts"]:::code
        L_Http["convex/http.ts"]:::code
        M_Users["convex/users.ts"]:::code
        N_AuthConfig["convex/auth.config.js"]:::code
        O_Generated["convex/_generated/"]:::code
        P_DB["Convex DB (messages, users)"]:::db
    end

    Q_ClerkAuth["Clerk Auth Service"]:::external
    R_ClerkWebhook["Clerk Webhook Service"]:::external

    A_HTML --> C_Main
    B_Vite --> C_Main
    C_Main --> D_App
    D_App --> E_Login
    D_App --> F_SignUp
    D_App --> G_Badge

    D_App -->|"authenticate"| Q_ClerkAuth
    Q_ClerkAuth -->|"JWT"| D_App

    D_App -->|"listMessages()"| J_List
    D_App -->|"sendMessage()"| K_Send

    J_List -->|"read"| P_DB
    K_Send -->|"write"| P_DB
    P_DB -->|"live updates"| D_App

    R_ClerkWebhook -->|"webhook"| L_Http
    L_Http -->|"update users"| M_Users
    M_Users -->|"write"| P_DB

    N_AuthConfig -.->|"JWT validation"| J_List
    N_AuthConfig -.->|"JWT validation"| K_Send

    click C_Main "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/src/main.tsx"
    click D_App "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/src/App.tsx"
    click E_Login "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/src/LoginPage.tsx"
    click F_SignUp "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/src/SigningUp.tsx"
    click G_Badge "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/src/Badge.tsx"
    click H_Styles "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/src/index.css"
    click A_HTML "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/index.html"
    click B_Vite "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/vite.config.ts"
    click I_Schema "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/convex/schema.ts"
    click J_List "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/convex/listMessages.ts"
    click K_Send "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/convex/sendMessage.ts"
    click L_Http "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/convex/http.ts"
    click M_Users "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/convex/users.ts"
    click N_AuthConfig "https://github.com/thomasballinger/convex-clerk-users-table/blob/main/convex/auth.config.js"
    click O_Generated "https://github.com/thomasballinger/convex-clerk-users-table/tree/main/convex/_generated/"

    classDef code fill:#D0E8FF,stroke:#333,color:#000
    classDef db fill:#C8E6C9,stroke:#333,color:#000
    classDef external fill:#FFE0B2,stroke:#333,color:#000
```
