# ketan-ag/smart-board architecture

> Architecture diagram of the GitHub repository ketan-ag/smart-board, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ketan-ag/smart-board
- Repository: https://github.com/ketan-ag/smart-board

## Overview

##### Project type and purpose
- This is a full-stack, real-time collaborative whiteboard (“Miro clone”) built on Next.js 13’s App Router.
- The front end is React + Tailwind; real-time sync uses Liveblocks; persistent storage and business logic use Convex; authentication is handled by Clerk.

##### File structure
- app/ – Next.js “App Router” pages and layouts
- (dashboard)/ – dashboard UI (board listing, org sidebar, nav)
- board/[boardId]/ – live board page (canvas, tools, presence)
- api/liveblocks-auth/route.ts – serverless API route for Liveblocks authentication
- components/ – shared React components (modals, UI primitives, actions)
- providers/ – React context for Convex client and modal state
- convex/ – Convex function definitions, schema, and generated client/server bindings
- hooks/ – custom React hooks for API mutations, selection logic, scroll locks
- types/, lib/, public/ – utility types, helper functions, static assets
- config files: next.config.mjs, tailwind.config.ts, liveblocks.config.ts, convex/auth.config.js

##### Key insights from README
- Stack: Next.js, Tailwind, Liveblocks, Convex, Clerk
- Tutorial-driven “Real Time Miro Clone”

##### Main architectural components
a. Frontend (Browser)
- Next.js App Router pages (dashboard & board)
- React component tree under app/ and components/
- Providers (ConvexClientProvider, ModalProvider)
- Liveblocks SDK client for real-time events (cursors, objects)
- Convex client for data queries & mutations
- Clerk client for user authentication flows
b. Next.js Backend (Edge / Serverless Functions)
- SSR/SSG rendering of app/* pages
- API Route: /api/liveblocks-auth → issues Liveblocks auth tokens
- Middleware (middleware.ts) for routing, auth checks
c. Convex Platform
- Convex Functions (convex/board.ts, convex/boards.ts)
- Convex Database (schema.ts)
- Generated client/server bindings (convex/_generated)
d. Liveblocks Service
- Real-time WebSocket rooms for board presence & updates
- Authenticated via Next.js API route
e. Clerk (Authentication Service)
- User sign-in, session management
- Integrated via Convex auth.config.js for serverless functions

##### Relationships and data flows
- Browser ←→ Next.js pages (SSR fetch + hydration)
- Browser (Convex client) → Convex functions → Convex DB
- Browser (Liveblocks SDK) ↔ Liveblocks real-time servers
- Presence updates (cursors, participants)
- Browser ←→ /api/liveblocks-auth (Next.js) to obtain Liveblocks tokens
- Browser ←→ Clerk-hosted auth endpoints (login, session, user info)
- Next.js middleware enforces auth on protected routes

##### Architectural patterns & principles
- BFF (Backend-for-Frontend): Next.js serverless functions abstract Liveblocks auth and Convex calls
- Provider pattern in React for global state (Convex, modals)
- Separation of concerns:
- UI / presentation (components/, app/)
- State & side-effects (hooks/)
- Data & business logic (convex/)
- Event-driven real-time collaboration (Liveblocks) vs. persistent state (Convex)

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Client Layer
  subgraph "Client (Browser)"
    direction TB
    DP["Dashboard Page"]:::client
    DL["Dashboard Layout"]:::client
    BP["Board Page"]:::client
    BSC["Board Subcomponents"]:::client
    UI["Shared UI Components"]:::client
    ACT["Application Actions"]:::client
    HK["Custom Hooks"]:::client
    PROV["Providers (Convex & Modal)"]:::client
    SDK_LB["Liveblocks SDK"]:::client
    SDK_CX["Convex JS SDK"]:::client
    SDK_CL["Clerk SDK"]:::client
  end

  %% Next.js Server / BFF Layer
  subgraph "Next.js Serverless / BFF" 
    direction TB
    SSR["SSR/SSG Rendering"]:::server
    API_LB["Liveblocks Auth API"]:::server
    MW["Middleware"]:::server
  end

  %% External Services Layer
  subgraph "External BaaS Services"
    direction TB
    LB["Liveblocks Service"]:::service
    subgraph "Convex Platform"
      direction TB
      CX_FN["Convex Functions"]:::service
      CX_DB["Convex Database"]:::service
      CX_GEN["Generated Bindings"]:::service
    end
    CL["Clerk Auth Service"]:::service
  end

  %% Connections
  DP -->|"hydrate & render"| SSR
  DL --> SSR
  BP -->|"SSR + Client Hydration"| SSR
  BSC --> BP
  UI --> DP
  UI --> BP
  ACT --> DP
  ACT --> BP
  HK --> DP
  HK --> BP
  PROV --> DP
  PROV --> BP
  SDK_LB -->|"WebSocket"| LB
  SDK_LB -->|"auth via API"| API_LB
  SDK_CX -->|"Convex JS SDK"| CX_FN
  SDK_CX -->|"query/mutate"| CX_DB
  SDK_CX -->|"uses bindings"| CX_GEN
  SDK_CL -->|"redirect/login"| CL

  SSR --> API_LB
  SSR --> CX_FN
  API_LB --> LB
  MW --> SSR
  MW --> API_LB

  CX_FN --> CX_DB
  CX_FN --> CX_GEN
  CX_FN --> CL

  %% Click Events
  click DP "https://github.com/ketan-ag/smart-board/blob/main/app/(dashboard)/page.tsx"
  click DL "https://github.com/ketan-ag/smart-board/blob/main/app/(dashboard)/layout.tsx"
  click BP "https://github.com/ketan-ag/smart-board/blob/main/app/board/[boardId]/page.tsx"
  click BSC "https://github.com/ketan-ag/smart-board/tree/main/app/board/[boardId]/_components/"
  click API_LB "https://github.com/ketan-ag/smart-board/blob/main/app/api/liveblocks-auth/route.ts"
  click MW "https://github.com/ketan-ag/smart-board/blob/main/middleware.ts"
  click UI "https://github.com/ketan-ag/smart-board/tree/main/components/ui/"
  click UI "https://github.com/ketan-ag/smart-board/tree/main/components/modals/"
  click ACT "https://github.com/ketan-ag/smart-board/blob/main/components/actions.tsx"
  click HK "https://github.com/ketan-ag/smart-board/blob/main/hooks/use-api-mutation.ts"
  click HK "https://github.com/ketan-ag/smart-board/blob/main/hooks/use-delete-layers.ts"
  click HK "https://github.com/ketan-ag/smart-board/blob/main/hooks/use-selection-bounds.ts"
  click HK "https://github.com/ketan-ag/smart-board/blob/main/hooks/use-disable-scroll-bounce.tsx"
  click PROV "https://github.com/ketan-ag/smart-board/blob/main/providers/convex-client-provider.tsx"
  click PROV "https://github.com/ketan-ag/smart-board/blob/main/providers/modal-provider.tsx"
  click CX_FN "https://github.com/ketan-ag/smart-board/blob/main/convex/board.ts"
  click CX_FN "https://github.com/ketan-ag/smart-board/blob/main/convex/boards.ts"
  click CX_DB "https://github.com/ketan-ag/smart-board/blob/main/convex/schema.ts"
  click CX_GEN "https://github.com/ketan-ag/smart-board/tree/main/convex/_generated/"
  click CL "https://github.com/ketan-ag/smart-board/blob/main/convex/auth.config.js"
  click LB "https://github.com/ketan-ag/smart-board/blob/main/liveblocks.config.ts"
  click SDK_CX "https://github.com/ketan-ag/smart-board/blob/main/tailwind.config.ts"
  click SSR "https://github.com/ketan-ag/smart-board/blob/main/next.config.mjs"
  click DP "https://github.com/ketan-ag/smart-board/blob/main/app/globals.css"
  click SDK_CL "https://github.com/ketan-ag/smart-board/blob/main/lib/utils.ts"
  click SDK_CL "https://github.com/ketan-ag/smart-board/blob/main/types/canvas.ts"
  click SDK_CL "https://github.com/ketan-ag/smart-board/tree/main/public/"
  click SDK_CL "https://github.com/ketan-ag/smart-board/blob/main/README.md"
  click SDK_CL "https://github.com/ketan-ag/smart-board/blob/main/package.json"
  click SDK_CL "https://github.com/ketan-ag/smart-board/blob/main/tsconfig.json"
  click SDK_CL "https://github.com/ketan-ag/smart-board/blob/main/postcss.config.js"
  click SDK_CL "https://github.com/ketan-ag/smart-board/blob/main/.eslintrc.json"

  %% Styles
  classDef client fill:#e0f7fa,stroke:#0288d1,color:#000
  classDef server fill:#e8f5e9,stroke:#2e7d32,color:#000
  classDef service fill:#fff3e0,stroke:#ef6c00,color:#000
```
