# nextcloud/whiteboard architecture

> Architecture diagram of the GitHub repository nextcloud/whiteboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nextcloud/whiteboard
- Repository: https://github.com/nextcloud/whiteboard

## Overview

Nextcloud Whiteboard is a browser-first collaborative drawing app. Users open or create a board, edit it in the Excalidraw-based UI, and save changes locally before syncing with Nextcloud; optional WebSocket sessions add live collaboration. The product also supports libraries and templates, comments and voting, version preview, and recordings. Edges are limited to relationships shown in excerpts or explicitly documented in the README; unsampled implementation details are represented only where the tree or README supports a subsystem.

Main entry points: [`src/App.tsx`](https://github.com/nextcloud/whiteboard/blob/main/src/App.tsx) (Whiteboard UI), [`src/hooks/useBoardDataManager.ts`](https://github.com/nextcloud/whiteboard/blob/main/src/hooks/useBoardDataManager.ts) (Board data manager), [`websocket_server/Services/SocketService.js`](https://github.com/nextcloud/whiteboard/blob/main/websocket_server/Services/SocketService.js) (Socket and room service), [`src/hooks/useVersionPreview.ts`](https://github.com/nextcloud/whiteboard/blob/main/src/hooks/useVersionPreview.ts) (Version preview)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser whiteboard"]
  node_editor["Whiteboard UI<br/>[App.tsx]"]
  node_client_entry["Client entry<br/>[main.ts]"]
  node_board_manager["Board data manager"]
  node_config_store["Board config"]
  node_jwt_store["JWT handling<br/>[useJwtStore.ts]"]
  node_version_preview["Version preview"]
  node_collab_hook["Collaboration client"]
  node_collab_store["Collaboration state"]
  node_comments["Board comments<br/>[CommentSidebar.tsx]"]
end

subgraph group_persistence["Board persistence"]
  node_local_db[("Local board database<br/>[db.ts]")]
  node_sync_worker["Background sync worker<br/>[syncWorker.ts]"]
  node_scene_sync["Scene sync utilities<br/>[syncSceneData.ts]"]
end

subgraph group_nextcloud["Nextcloud app"]
  node_board_api["Board API controller"]
  node_content_service["Board content service"]
  node_jwt_service["JWT service<br/>[JWTService.php]"]
  node_config_service["App configuration<br/>[ConfigService.php]"]
  node_canvas_templates["Canvas templates"]
  node_libraries["Whiteboard libraries"]
end

subgraph group_realtime["Live collaboration"]
  node_websocket_server["WebSocket server<br/>[main.js]"]
  node_socket_service["Socket and room service<br/>[SocketService.js]"]
  node_session_storage[("Session storage<br/>[StorageService.js]")]
  node_recording["Board recording"]
  node_presentation["Presentation controls"]
  node_voting["Voting controls<br/>[VotingService.js]"]
end

node_user(("Board user"))
node_nextcloud["Nextcloud platform"]

node_user -->|"opens and edits"| node_editor
node_client_entry -->|"renders"| node_editor
node_editor -->|"loads board data"| node_board_manager
node_board_manager -->|"reads and writes"| node_local_db
node_board_manager -->|"fetches board"| node_nextcloud
node_board_manager -->|"checks board state"| node_config_store
node_board_manager -->|"uses token"| node_jwt_store
node_sync_worker -->|"reads and writes"| node_local_db
node_sync_worker -->|"uses sync helpers"| node_scene_sync
node_editor -.->|"starts collaboration"| node_collab_hook
node_collab_hook -.->|"updates state"| node_collab_store
node_collab_hook -.->|"joins live session"| node_websocket_server
node_websocket_server -->|"starts service"| node_socket_service
node_socket_service -->|"uses storage service"| node_session_storage
node_socket_service -->|"dispatches controls"| node_presentation
node_socket_service -->|"dispatches controls"| node_voting
node_user -->|"requests board"| node_nextcloud
node_nextcloud -->|"routes requests"| node_board_api
node_board_api -->|"reads board content"| node_content_service
node_board_api -->|"validates token"| node_jwt_service
node_jwt_service -->|"gets signing secret"| node_config_service
node_editor -.->|"loads libraries"| node_libraries
node_editor -.->|"uses templates"| node_canvas_templates
node_editor -.->|"previews versions"| node_version_preview
node_version_preview -->|"updates local copy"| node_local_db
node_version_preview -->|"restores version"| node_nextcloud
node_editor -->|"shows sidebar"| node_comments
node_user -.->|"records board"| node_recording

click node_editor "https://github.com/nextcloud/whiteboard/blob/main/src/App.tsx"
click node_client_entry "https://github.com/nextcloud/whiteboard/blob/main/src/main.ts"
click node_board_manager "https://github.com/nextcloud/whiteboard/blob/main/src/hooks/useBoardDataManager.ts"
click node_config_store "https://github.com/nextcloud/whiteboard/blob/main/src/stores/useWhiteboardConfigStore.ts"
click node_jwt_store "https://github.com/nextcloud/whiteboard/blob/main/src/stores/useJwtStore.ts"
click node_version_preview "https://github.com/nextcloud/whiteboard/blob/main/src/hooks/useVersionPreview.ts"
click node_local_db "https://github.com/nextcloud/whiteboard/blob/main/src/database/db.ts"
click node_sync_worker "https://github.com/nextcloud/whiteboard/blob/main/src/workers/syncWorker.ts"
click node_scene_sync "https://github.com/nextcloud/whiteboard/blob/main/src/utils/syncSceneData.ts"
click node_board_api "https://github.com/nextcloud/whiteboard/blob/main/lib/Controller/WhiteboardController.php"
click node_content_service "https://github.com/nextcloud/whiteboard/blob/main/lib/Service/WhiteboardContentService.php"
click node_jwt_service "https://github.com/nextcloud/whiteboard/blob/main/lib/Service/JWTService.php"
click node_config_service "https://github.com/nextcloud/whiteboard/blob/main/lib/Service/ConfigService.php"
click node_canvas_templates "https://github.com/nextcloud/whiteboard/blob/main/lib/Service/CanvasTemplateService.php"
click node_libraries "https://github.com/nextcloud/whiteboard/blob/main/lib/Service/WhiteboardLibraryService.php"
click node_collab_hook "https://github.com/nextcloud/whiteboard/blob/main/src/hooks/useCollaboration.ts"
click node_collab_store "https://github.com/nextcloud/whiteboard/blob/main/src/stores/useCollaborationStore.ts"
click node_websocket_server "https://github.com/nextcloud/whiteboard/blob/main/websocket_server/main.js"
click node_socket_service "https://github.com/nextcloud/whiteboard/blob/main/websocket_server/Services/SocketService.js"
click node_session_storage "https://github.com/nextcloud/whiteboard/blob/main/websocket_server/Services/StorageService.js"
click node_recording "https://github.com/nextcloud/whiteboard/blob/main/websocket_server/Services/RecordingService.js"
click node_presentation "https://github.com/nextcloud/whiteboard/blob/main/websocket_server/Services/PresentationService.js"
click node_voting "https://github.com/nextcloud/whiteboard/blob/main/websocket_server/Services/VotingService.js"
click node_comments "https://github.com/nextcloud/whiteboard/blob/main/src/components/CommentSidebar.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_editor,node_client_entry,node_board_manager,node_config_store,node_jwt_store,node_version_preview,node_collab_hook,node_collab_store,node_comments,node_user toneBlue
class node_local_db,node_sync_worker,node_scene_sync toneAmber
class node_board_api,node_content_service,node_jwt_service,node_config_service,node_canvas_templates,node_libraries toneMint
class node_websocket_server,node_socket_service,node_session_storage,node_recording,node_presentation,node_voting toneRose
class node_nextcloud toneIndigo
```

## Components

### Browser whiteboard

- [Whiteboard UI](https://github.com/nextcloud/whiteboard/blob/main/src/App.tsx): `src/App.tsx`
- [Client entry](https://github.com/nextcloud/whiteboard/blob/main/src/main.ts): `src/main.ts`
- [Board data manager](https://github.com/nextcloud/whiteboard/blob/main/src/hooks/useBoardDataManager.ts): `src/hooks/useBoardDataManager.ts`
- [Board config](https://github.com/nextcloud/whiteboard/blob/main/src/stores/useWhiteboardConfigStore.ts): `src/stores/useWhiteboardConfigStore.ts`
- [JWT handling](https://github.com/nextcloud/whiteboard/blob/main/src/stores/useJwtStore.ts): `src/stores/useJwtStore.ts`
- [Version preview](https://github.com/nextcloud/whiteboard/blob/main/src/hooks/useVersionPreview.ts): `src/hooks/useVersionPreview.ts`
- [Collaboration client](https://github.com/nextcloud/whiteboard/blob/main/src/hooks/useCollaboration.ts): `src/hooks/useCollaboration.ts`
- [Collaboration state](https://github.com/nextcloud/whiteboard/blob/main/src/stores/useCollaborationStore.ts): `src/stores/useCollaborationStore.ts`
- [Board comments](https://github.com/nextcloud/whiteboard/blob/main/src/components/CommentSidebar.tsx): `src/components/CommentSidebar.tsx`

### Board persistence

- [Local board database](https://github.com/nextcloud/whiteboard/blob/main/src/database/db.ts): `src/database/db.ts`
- [Background sync worker](https://github.com/nextcloud/whiteboard/blob/main/src/workers/syncWorker.ts): `src/workers/syncWorker.ts`
- [Scene sync utilities](https://github.com/nextcloud/whiteboard/blob/main/src/utils/syncSceneData.ts): `src/utils/syncSceneData.ts`

### Nextcloud app

- [Board API controller](https://github.com/nextcloud/whiteboard/blob/main/lib/Controller/WhiteboardController.php): `lib/Controller/WhiteboardController.php`
- [Board content service](https://github.com/nextcloud/whiteboard/blob/main/lib/Service/WhiteboardContentService.php): `lib/Service/WhiteboardContentService.php`
- [JWT service](https://github.com/nextcloud/whiteboard/blob/main/lib/Service/JWTService.php): `lib/Service/JWTService.php`
- [App configuration](https://github.com/nextcloud/whiteboard/blob/main/lib/Service/ConfigService.php): `lib/Service/ConfigService.php`
- [Canvas templates](https://github.com/nextcloud/whiteboard/blob/main/lib/Service/CanvasTemplateService.php): `lib/Service/CanvasTemplateService.php`
- [Whiteboard libraries](https://github.com/nextcloud/whiteboard/blob/main/lib/Service/WhiteboardLibraryService.php): `lib/Service/WhiteboardLibraryService.php`

### Live collaboration

- [WebSocket server](https://github.com/nextcloud/whiteboard/blob/main/websocket_server/main.js): `websocket_server/main.js`
- [Socket and room service](https://github.com/nextcloud/whiteboard/blob/main/websocket_server/Services/SocketService.js): `websocket_server/Services/SocketService.js`
- [Session storage](https://github.com/nextcloud/whiteboard/blob/main/websocket_server/Services/StorageService.js): `websocket_server/Services/StorageService.js`
- [Board recording](https://github.com/nextcloud/whiteboard/blob/main/websocket_server/Services/RecordingService.js): `websocket_server/Services/RecordingService.js`
- [Presentation controls](https://github.com/nextcloud/whiteboard/blob/main/websocket_server/Services/PresentationService.js): `websocket_server/Services/PresentationService.js`
- [Voting controls](https://github.com/nextcloud/whiteboard/blob/main/websocket_server/Services/VotingService.js): `websocket_server/Services/VotingService.js`

### Other components

- **Board user**
- **Nextcloud platform**

## Connections

- Board user → Whiteboard UI: opens and edits (evidence: `README.md`)
- Client entry → Whiteboard UI: renders (evidence: `src/main.ts`)
- Whiteboard UI → Board data manager: loads board data (evidence: `src/App.tsx`)
- Board data manager → Local board database: reads and writes (evidence: `src/hooks/useBoardDataManager.ts`)
- Board data manager → Nextcloud platform: fetches board (evidence: `src/hooks/useBoardDataManager.ts`)
- Board data manager → Board config: checks board state (evidence: `src/hooks/useBoardDataManager.ts`)
- Board data manager → JWT handling: uses token (evidence: `src/hooks/useBoardDataManager.ts`)
- Background sync worker → Local board database: reads and writes (evidence: `src/workers/syncWorker.ts`)
- Background sync worker → Scene sync utilities: uses sync helpers (evidence: `src/workers/syncWorker.ts`)
- Whiteboard UI → Collaboration client: starts collaboration (evidence: `src/App.tsx`)
- Collaboration client → Collaboration state: updates state
- Collaboration client → WebSocket server: joins live session (evidence: `README.md`)
- WebSocket server → Socket and room service: starts service (evidence: `websocket_server/main.js`)
- Socket and room service → Session storage: uses storage service (evidence: `websocket_server/Services/SocketService.js`)
- Socket and room service → Presentation controls: dispatches controls (evidence: `websocket_server/Services/SocketService.js`)
- Socket and room service → Voting controls: dispatches controls (evidence: `websocket_server/Services/SocketService.js`)
- Board user → Nextcloud platform: requests board (evidence: `README.md`)
- Nextcloud platform → Board API controller: routes requests
- Board API controller → Board content service: reads board content (evidence: `lib/Controller/WhiteboardController.php`)
- Board API controller → JWT service: validates token (evidence: `lib/Controller/WhiteboardController.php`)
- JWT service → App configuration: gets signing secret (evidence: `lib/Service/JWTService.php`)
- Whiteboard UI → Whiteboard libraries: loads libraries (evidence: `src/App.tsx`)
- Whiteboard UI → Canvas templates: uses templates (evidence: `README.md`)
- Whiteboard UI → Version preview: previews versions (evidence: `src/App.tsx`)
- Version preview → Local board database: updates local copy (evidence: `src/hooks/useVersionPreview.ts`)
- Version preview → Nextcloud platform: restores version (evidence: `src/hooks/useVersionPreview.ts`)
- Whiteboard UI → Board comments: shows sidebar (evidence: `src/App.tsx`)
- Board user → Board recording: records board (evidence: `README.md`)
