# ikumar200/livedocs architecture

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

- Interactive diagram: https://gitdiagram.com/ikumar200/livedocs
- Repository: https://github.com/ikumar200/livedocs

## Overview

##### Project Type & Purpose
– This is a full-stack, real-time collaborative document editor built on Next.js 13 (App Router).
– It uses Convex as a BaaS for persistence and business logic, and Liveblocks for real-time presence and synchronization.

##### High-Level Components
A. Browser Clients
- Next.js rendered UI (Server Components + Client Components)
- Tiptap-based rich-text editor with custom extensions (font-size, line-height)
- Zustand-style store hooks (use-editor-store, use-toast)
- Convex client (via convex-client-provider)
- Liveblocks client (connected via WebSocket)

B. Next.js App (deployed on Vercel)
- App Router routes (/, /documents/[documentId])
- API Route: /api/liveblocks-auth → issues Liveblocks auth tokens
- Server Components: layout.tsx, navbar, global CSS, font loading
- Client Components: document-input, editor, toolbar, threads, room, ruler

C. Convex Backend Service
- Schema (convex/schema.ts) defining Documents, Threads, Comments
- Documents logic (convex/documents.ts) for CRUD & real-time subscriptions
- Generated API & server code (convex/_generated)
- Auth config (convex/auth.config.ts) integrating user identity

D. Liveblocks Real-Time Service
- Room management (presence, cursors, storage)
- Access controlled via tokens from Next.js API

E. External Infrastructure
- Vercel Hosting + CDN for static assets (public/)
- npm ecosystem (Tailwind, PostCSS, ESlint, TypeScript)

##### Component Interactions & Data Flows
1) User opens app → Next.js SSR/SSG serves HTML + JS
2) Browser initializes Convex client → fetches document list/table
3) On “open document”:
- Client subscribes to Convex live query for content
- Client calls Next.js /api/liveblocks-auth → receives Liveblocks token
- Client connects to Liveblocks WebSocket room for real-time edits
4) Editing workflow:
- Local Tiptap changes → update client store →
- Broadcast to Liveblocks peers → merge and display cursors
- On save or auto-save → send mutation to Convex → persist to DB
- Convex push updates to other subscribers

##### Architectural Patterns & Principles
– BaaS/CaaS: Convex abstracts server logic, data model, subscriptions
– Pub/Sub Real-Time: Liveblocks for low-latency collaborative events
– Hybrid Rendering: Next.js Server Components for layout & data fetching, Client Components for interactivity
– Separation of Concerns:
- UI & styling in /components/ui + Tailwind
- Business logic in convex/
- Real-time logic in Liveblocks API route + client

##### Representation Details
– Clear labels for: Next.js SSR, Server Components, Client Components, API Routes

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Presentation Layer
  subgraph "Presentation Layer" 
    direction TB
    Browser["Browser Client"]:::frontend
    UI_Folder["src/app"]:::frontend
    Components_Folder["src/components"]:::frontend
    UI_UI_Folder["src/components/ui"]:::frontend
    Tiptap["Tiptap Editor"]:::frontend
    FontSizeExt["font-size extension"]:::frontend
    LineHeightExt["line-height extension"]:::frontend
    StoreFolder["src/store/use-editor-store.ts"]:::frontend
    ToastHook["src/hooks/use-toast.ts"]:::frontend
    ConvexProv["Convex Client Provider"]:::frontend
    LiveCfg["liveblocks.config.ts"]:::frontend
  end

  click UI_Folder "https://github.com/ikumar200/livedocs/tree/main/src/app"
  click Components_Folder "https://github.com/ikumar200/livedocs/tree/main/src/components"
  click UI_UI_Folder "https://github.com/ikumar200/livedocs/tree/main/src/components/ui"
  click FontSizeExt "https://github.com/ikumar200/livedocs/blob/main/src/extensions/font-size.ts"
  click LineHeightExt "https://github.com/ikumar200/livedocs/blob/main/src/extensions/line-height.ts"
  click StoreFolder "https://github.com/ikumar200/livedocs/blob/main/src/store/use-editor-store.ts"
  click ToastHook "https://github.com/ikumar200/livedocs/blob/main/src/hooks/use-toast.ts"
  click ConvexProv "https://github.com/ikumar200/livedocs/blob/main/src/components/convex-client-provider.tsx"
  click LiveCfg "https://github.com/ikumar200/livedocs/blob/main/liveblocks.config.ts"

  %% Next.js App Router
  subgraph "Next.js App Router (Vercel)" 
    direction TB
    HomePage["Home Page<br/>(documents list)"]:::frontend
    DocMenu["document-menu"]:::frontend
    DocsTable["documents-table"]:::frontend
    DocRow["document-row"]:::frontend
    SearchInput["search-input"]:::frontend
    Templates["templates-gallery"]:::frontend
    subgraph "Document Routes"
      direction TB
      DocPage["[documentId] Page"]:::frontend
      Loading["loading.tsx"]:::frontend
      Navbar["navbar.tsx"]:::frontend
      DocInput["document-input.tsx"]:::frontend
      EditorComp["editor.tsx"]:::frontend
      Toolbar["toolbar.tsx"]:::frontend
      Threads["threads.tsx"]:::frontend
      RoomComp["room.tsx"]:::frontend
      Ruler["ruler.tsx"]:::frontend
    end
    Layout["layout.tsx"]:::frontend
    GlobalsCSS["globals.css"]:::frontend
    Fonts["src/app/fonts/*"]:::frontend
    APIAuth["/api/liveblocks-auth"]:::frontend
  end

  click HomePage "https://github.com/ikumar200/livedocs/blob/main/src/app/(home)/page.tsx"
  click DocMenu "https://github.com/ikumar200/livedocs/blob/main/src/app/(home)/document-menu.tsx"
  click DocsTable "https://github.com/ikumar200/livedocs/blob/main/src/app/(home)/documents-table.tsx"
  click DocRow "https://github.com/ikumar200/livedocs/blob/main/src/app/(home)/document-row.tsx"
  click SearchInput "https://github.com/ikumar200/livedocs/blob/main/src/app/(home)/search-input.tsx"
  click Templates "https://github.com/ikumar200/livedocs/blob/main/src/app/(home)/templates-gallery.tsx"
  click DocPage "https://github.com/ikumar200/livedocs/blob/main/src/app/documents/[documentId]/page.tsx"
  click Loading "https://github.com/ikumar200/livedocs/blob/main/src/app/documents/[documentId]/loading.tsx"
  click Navbar "https://github.com/ikumar200/livedocs/blob/main/src/app/documents/[documentId]/navbar.tsx"
  click DocInput "https://github.com/ikumar200/livedocs/blob/main/src/app/documents/[documentId]/document-input.tsx"
  click EditorComp "https://github.com/ikumar200/livedocs/blob/main/src/app/documents/[documentId]/editor.tsx"
  click Toolbar "https://github.com/ikumar200/livedocs/blob/main/src/app/documents/[documentId]/toolbar.tsx"
  click Threads "https://github.com/ikumar200/livedocs/blob/main/src/app/documents/[documentId]/threads.tsx"
  click RoomComp "https://github.com/ikumar200/livedocs/blob/main/src/app/documents/[documentId]/room.tsx"
  click Ruler "https://github.com/ikumar200/livedocs/blob/main/src/app/documents/[documentId]/ruler.tsx"
  click Layout "https://github.com/ikumar200/livedocs/blob/main/src/app/layout.tsx"
  click GlobalsCSS "https://github.com/ikumar200/livedocs/blob/main/src/app/globals.css"

  click APIAuth "https://github.com/ikumar200/livedocs/blob/main/src/app/api/liveblocks-auth/route.ts"

  %% Convex Backend
  subgraph "Convex Backend Service" 
    direction TB
    Schema["convex/schema.ts"]:::backend
    Logic["convex/documents.ts"]:::backend
    AuthC["convex/auth.config.ts"]:::backend
    Generated["convex/_generated"]:::backend
    DB[(Convex Database)]:::backend
  end

  click Schema "https://github.com/ikumar200/livedocs/blob/main/convex/schema.ts"
  click Logic "https://github.com/ikumar200/livedocs/blob/main/convex/documents.ts"
  click AuthC "https://github.com/ikumar200/livedocs/blob/main/convex/auth.config.ts"
  click Generated "https://github.com/ikumar200/livedocs/tree/main/convex/_generated/"

  %% Liveblocks Real-Time Service
  Liveblocks["Liveblocks Service"]:::realtime

  %% CDN/Hosting
  subgraph "CDN/Hosting & Static Assets"
    direction TB
    Public["public/"]:::static
  end

  click Public "https://github.com/ikumar200/livedocs/tree/main/public/"

  %% Data Flows
  Browser -->|"HTTP GET HTML/JS"| HomePage
  Browser -->|"HTTP GET HTML/JS"| DocPage
  Browser -->|"Convex SDK"| Schema
  Browser -->|"WebSocket"| Liveblocks
  APIAuth -->|"HTTP POST auth token"| Liveblocks
  HomePage -->|"Convex SDK fetch list"| Schema
  DocPage -->|"Convex live query"| Logic
  DocPage -->|"fetch token"| APIAuth
  DocPage -->|"WebSocket connect"| Liveblocks
  EditorComp -->|"mutation"| Logic
  Logic -->|"push updates"| DocPage
  Public -->|"served via CDN"| Browser

  %% Class Definitions
  classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
  classDef backend fill:#d4edda,stroke:#155724,color:#155724;
  classDef realtime fill:#fff3cd,stroke:#856404,color:#856404;
  classDef static fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
