# chunkangwong/slack-clone architecture

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

- Interactive diagram: https://gitdiagram.com/chunkangwong/slack-clone
- Repository: https://github.com/chunkangwong/slack-clone

## Overview

##### Project type and purpose
- This is a full-stack, real-time chat application (“Slack clone”) built with Next.js on the frontend, Convex for backend functions and data, and shadcn/ui for styling.
- Users can sign in/up, create or join workspaces, channels, direct-message other members, send/receive messages, react, and upload attachments.

##### File structure
- Top-level config files: next.config.mjs, tsconfig.json, tailwind.config.ts, bun.lockb, package.json
- “convex/”: all backend functions, API definitions, schema & auth config
- “src/app/”: Next.js 13 “app” directory—page routes for auth, join, workspace, channel, member
- “src/components/” & “src/features/”: React UI components and feature slices (auth, channels, messages, workspaces, members, reactions, upload)
- “src/hooks/” and “src/lib/”: custom hooks and utilities
- Middleware.ts, React-Query & Convex providers, static assets in “public”

##### Key insights from the README
- Uses Next.js for SSR/SSG & routing, @convex/react & custom hooks for data fetching/mutations, React-Query wrapper for caching, react-hook-form for forms
- Deployed serverless on Vercel, Convex functions run in a serverless environment and persist in Convex’s database

##### Main components and their relationships
a. Frontend (Next.js App)
- Browser ▶ Next.js pages & layouts ▶ React components
- Uses UI library (shadcn/ui) + feature modules + custom hooks
- React-Query & Convex client provider handle data fetching & mutations
b. Backend (Convex Serverless Functions)
- Endpoints defined in convex/*.ts (e.g., messages.ts, channels.ts, auth.ts)
- Exposed via the Convex client (uses api.js / server.js under the hood)
c. Database (Convex Data Storage)
- Schema defined in convex/schema.ts
- All reads/writes happen through Convex functions for security rules
d. Authentication & Authorization
- Managed by Convex’s auth.config.ts plus Next.js middleware
e. File Uploads
- generateUploadUrl Convex function returns signed URL; client uploads to (likely) a cloud storage bucket
f. Hosting & Deployment
- Next.js static assets and serverless functions on Vercel
- Convex functions & DB in Convex cloud

##### Architectural patterns & design principles
- Client-Server separation: Next.js frontend vs. Convex backend
- Feature-based folder structure in frontend: each domain (channels, messages, workspaces, etc.) has its own API hooks, components & store logic
- Serverless functions as micro-endpoints: each Convex file maps to a logical operation
- Data fetching & caching with React-Query & custom hooks
- Form management with react-hook-form

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Next.js App)" 
        direction TB
        Browser["User's Browser"]:::external
        NextApp["Next.js Pages & Layouts"]:::frontend
        UIComp["React UI Components"]:::frontend
        UILib["UI Library (shadcn/ui)"]:::frontend
        Features["Feature Modules"]:::frontend
        Hooks["Custom Hooks"]:::frontend
        Utils["Utility Functions"]:::frontend
        Providers["Providers\n(Convex & ReactQuery)"]:::frontend
    end

    %% Serverless Functions Layer
    subgraph "Convex Serverless Functions" 
        direction TB
        AuthFunc["Auth & User Functions"]:::functions
        WorkspaceFunc["Workspaces Functions"]:::functions
        ChannelFunc["Channels Functions"]:::functions
        ConvFunc["Conversations Functions"]:::functions
        MemberFunc["Members Functions"]:::functions
        MessageFunc["Messages Functions"]:::functions
        ReactionFunc["Reactions Functions"]:::functions
        UploadFunc["File Upload URL Generator"]:::functions
        HTTPFunc["HTTP Bridge"]:::functions
    end

    %% Database Layer
    subgraph "Convex Database" 
        Schema["Schema Definitions"]:::db
        AuthConfig["Auth Config"]:::db
        GenBindings["Generated Bindings"]:::db
    end

    %% External Services
    subgraph "External Services & Hosting"
        direction TB
        FileStorage["File Storage\n(Attachments)"]:::external
        Vercel["Vercel Hosting"]:::external
        ConvexCloud["Convex Cloud"]:::external
    end

    %% Config & Middleware
    subgraph "Config & Deployment"
        direction TB
        NextConfig["next.config.mjs"]:::external
        TailwindConf["tailwind.config.ts"]:::external
        TSConfig["tsconfig.json"]:::external
        PackageJSON["package.json"]:::external
        BunLock["bun.lockb"]:::external
        PostCSS["postcss.config.mjs"]:::external
        Middleware["Next.js Middleware"]:::external
        StaticAssets["Static Assets (public)"]:::external
    end

    %% Relationships
    Browser -->|"navigates"| NextApp
    NextApp -->|"renders UI"| UIComp
    NextApp -->|"uses UI Library"| UILib
    UIComp -->|"calls hooks"| Hooks
    UIComp -->|"imports utils"| Utils
    NextApp -->|"<ConvexClientProvider>"| Providers
    NextApp -->|"<ReactQueryProvider>"| Providers

    Providers -->|"query/mutation"| AuthFunc
    Providers -->|"query/mutation"| WorkspaceFunc
    Providers -->|"query/mutation"| ChannelFunc
    Providers -->|"query/mutation"| ConvFunc
    Providers -->|"query/mutation"| MemberFunc
    Providers -->|"query/mutation"| MessageFunc
    Providers -->|"query/mutation"| ReactionFunc
    Providers -->|"mutation(uploadUrl)"| UploadFunc
    Providers -->|"http calls"| HTTPFunc

    AuthFunc -->|"reads/writes"| Schema
    WorkspaceFunc -->|"reads/writes"| Schema
    ChannelFunc -->|"reads/writes"| Schema
    ConvFunc -->|"reads/writes"| Schema
    MemberFunc -->|"reads/writes"| Schema
    MessageFunc -->|"reads/writes"| Schema
    ReactionFunc -->|"reads/writes"| Schema
    UploadFunc -->|"generates URL"| FileStorage

    AuthFunc -->|"validates tokens"| AuthConfig
    AuthConfig -->|"enforces rules"| Schema

    Vercel -->|"deploys Frontend & Functions"| NextApp
    ConvexCloud -->|"hosts functions & DB"| AuthFunc
    ConvexCloud -->|"hosts functions & DB"| Schema

    %% Click Events
    click NextApp "https://github.com/chunkangwong/slack-clone/tree/main/src/app"
    click UIComp "https://github.com/chunkangwong/slack-clone/tree/main/src/components"
    click UILib "https://github.com/chunkangwong/slack-clone/tree/main/src/components/ui"
    click Features "https://github.com/chunkangwong/slack-clone/tree/main/src/features"
    click Hooks "https://github.com/chunkangwong/slack-clone/tree/main/src/hooks"
    click Utils "https://github.com/chunkangwong/slack-clone/blob/main/src/lib/utils.ts"
    click Providers "https://github.com/chunkangwong/slack-clone/blob/main/src/components/convex-client-provider.tsx"
    click Providers "https://github.com/chunkangwong/slack-clone/blob/main/src/components/react-query-provider.tsx"
    click AuthFunc "https://github.com/chunkangwong/slack-clone/blob/main/convex/auth.ts"
    click AuthFunc "https://github.com/chunkangwong/slack-clone/blob/main/convex/user.ts"
    click WorkspaceFunc "https://github.com/chunkangwong/slack-clone/blob/main/convex/workspaces.ts"
    click ChannelFunc "https://github.com/chunkangwong/slack-clone/blob/main/convex/channels.ts"
    click ConvFunc "https://github.com/chunkangwong/slack-clone/blob/main/convex/conversations.ts"
    click MemberFunc "https://github.com/chunkangwong/slack-clone/blob/main/convex/members.ts"
    click MessageFunc "https://github.com/chunkangwong/slack-clone/blob/main/convex/messages.ts"
    click ReactionFunc "https://github.com/chunkangwong/slack-clone/blob/main/convex/reactions.ts"
    click UploadFunc "https://github.com/chunkangwong/slack-clone/blob/main/convex/upload.ts"
    click HTTPFunc "https://github.com/chunkangwong/slack-clone/blob/main/convex/http.ts"
    click Schema "https://github.com/chunkangwong/slack-clone/blob/main/convex/schema.ts"
    click AuthConfig "https://github.com/chunkangwong/slack-clone/blob/main/convex/auth.config.ts"
    click GenBindings "https://github.com/chunkangwong/slack-clone/tree/main/convex/_generated"
    click Middleware "https://github.com/chunkangwong/slack-clone/blob/main/middleware.ts"
    click StaticAssets "https://github.com/chunkangwong/slack-clone/tree/main/public"
    click NextConfig "https://github.com/chunkangwong/slack-clone/blob/main/next.config.mjs"
    click TailwindConf "https://github.com/chunkangwong/slack-clone/blob/main/tailwind.config.ts"
    click TSConfig "https://github.com/chunkangwong/slack-clone/blob/main/tsconfig.json"
    click PackageJSON "https://github.com/chunkangwong/slack-clone/blob/main/package.json"
    click BunLock "https://github.com/chunkangwong/slack-clone/blob/main/bun.lockb"
    click PostCSS "https://github.com/chunkangwong/slack-clone/blob/main/postcss.config.mjs"

    %% Styles
    classDef frontend fill:#cfe2ff,stroke:#3182ce,color:#1e40af
    classDef functions fill:#ffe5b4,stroke:#dd6b20,color:#9c4221
    classDef db fill:#d1fae5,stroke:#047857,color:#065f46
    classDef external fill:#e2e8f0,stroke:#4a5568,color:#2d3748
```
