Whiteboard UI

Relevant source files

The following files were used as context for generating this wiki page:

• apps/portal/pages/media/whiteboards.tsx
• apps/portal/pages/whiteboard/[whiteboardID].tsx
• apps/portal/components/pagesComponents/_whiteboardsScreen/WhiteboardContainer/WhiteboardCard/WhiteboardCard.tsx
• apps/portal/app/services/whiteboards.ts
• apps/portal/app/interfaces/IWhiteboard.ts
• apps/api/src/module/whiteboards/controllers/whiteboard.controller.ts
• apps/api/src/module/whiteboards/services/whiteboards.service.ts

The Whiteboard UI is a core feature of the Ever Rec platform, providing users with a versatile digital canvas for collaboration. It enables the creation, annotation, and sharing of visual content, seamlessly integrated with the platform's screen capture and recording capabilities. Users can manage their whiteboards from a central dashboard, edit them in a feature-rich editor, and share them with others via public links.

The system is composed of two main parts: a management screen for viewing and organizing all whiteboards, and a detailed editor view for real-time drawing and commenting. The entire feature is built using Next.js on the frontend, with state managed by Redux, and a NestJS backend that uses Firebase for data persistence.

Sources: README.md, apps/portal/pages/media/whiteboards.tsx

Architecture Overview

The Whiteboard UI is split between a main listing page (WhiteboardsScreen) and the individual editor page (WhiteboardEditor). The listing page displays all user-owned whiteboards as cards, providing options for creation, filtering, and navigation. Clicking on a card or creating a new one navigates the user to the editor, which is a dynamic page powered by the Konva.js library for canvas rendering.

This diagram illustrates the high-level component structure of the Whiteboard feature.

Data Model

The core data structure for the whiteboard is defined by the IWhiteboard interface. This model is used consistently across the frontend portal and the backend API.

Sources: apps/portal/app/interfaces/IWhiteboard.ts, apps/api/src/module/whiteboards/interfaces/Whiteboard.ts

IWhiteboard Interface

This diagram shows the entity relationship for the IWhiteboard object.

The table below describes each field in the IWhiteboard interface.

Field	Type	Description
id	string	The unique identifier for the whiteboard, generated using nanoid.
name	string	The user-defined name of the whiteboard.
admin	string	The UID of the user who created and owns the whiteboard.
created	number	A timestamp indicating when the whiteboard was created.
trash	boolean	A flag to indicate if the whiteboard is in the bin.
favorite	boolean	A flag to indicate if the whiteboard is marked as a favorite.
isPublic	boolean	A flag to indicate if the whiteboard is publicly accessible via a share link.
thumbnail	string (optional)	A URL to a thumbnail image representing the whiteboard's content.

Sources: apps/portal/app/interfaces/IWhiteboard.ts, apps/api/src/module/whiteboards/services/whiteboards.service.ts:41-49

Core Components

Whiteboards Screen

The WhiteboardsScreen is the main dashboard for managing whiteboards. It fetches and displays all whiteboards belonging to the user.

• File: apps/portal/pages/media/whiteboards.tsx
• Responsibilities:
  • Fetches the user's whiteboards on component mount using getUserWhiteboards.
  • Renders the WhiteboardContainer, which displays WhiteboardCard components for each item.
  • Manages the visibility of the CreateNewWhiteboardModal to allow users to create new whiteboards.
  • Uses Redux to manage the list of whiteboards and loading state.

Sources: apps/portal/pages/media/whiteboards.tsx:10-40

Whiteboard Card

Each whiteboard is represented by a WhiteboardCard in the WhiteboardContainer. This component displays a thumbnail and name, and provides a menu for actions like renaming, sharing, and deleting.

• File: apps/portal/components/pagesComponents/_whiteboardsScreen/WhiteboardContainer/WhiteboardCard/WhiteboardCard.tsx
• Features:
  • Displays whiteboard name and thumbnail.
  • Provides a context menu with options: Open, Copy Link, Share, Rename, Add to Favorites, Move to Bin.
  • Handles API calls for actions like renameWboard, shareWboard, moveWhiteboardToBin, and deleteWBoard.
  • Dispatches Redux actions to update the application state after an operation is successful.

Sources: apps/portal/components/pagesComponents/_whiteboardsScreen/WhiteboardContainer/WhiteboardCard/WhiteboardCard.tsx

Whiteboard Editor

The WhiteboardEditor is the interactive canvas where users can draw, add comments, and manipulate objects. It is a dynamic page that loads a specific whiteboard based on the whiteboardID in the URL.

• File: apps/portal/pages/whiteboard/[whiteboardID].tsx
• Key Technologies:
  • Konva.js: Used to create and manage the HTML5 Canvas stage, layers, and shapes.
  • React: Manages component state, such as the active tool, scale, and selected objects.
• Functionality:
  • Initializes a Konva Stage to serve as the main drawing area.
  • Fetches whiteboard data using getWhiteboardById or getWhiteboardByIdShared based on the URL query.
  • Includes a Toolbar to select drawing tools (e.g., pointer, drawer, comments).
  • Includes a Sidebar to display and manage frames and layers within the canvas.
  • Handles tool-specific logic, such as initFreeDraw for drawing and initCommentDraw for placing comments.
  • Manages object transformation (moving, resizing) and snapping guides for alignment.

Sources: apps/portal/pages/whiteboard/[whiteboardID].tsx:14-385

Key Workflows

Creating a New Whiteboard

This sequence diagram shows the flow of creating a new whiteboard, from user input to the final UI update.

Updating a Whiteboard

Users can update various properties of a whiteboard, such as its name, favorite status, or whether it's in the trash. All these actions are handled by a single API endpoint.

• The WhiteboardCard component calls specific functions like renameWboard, favoriteWhiteboardHandler, or moveWhiteboardToBin.
• These functions in turn call service functions from apps/portal/app/services/whiteboards.ts (e.g., renameWhiteboard, favoriteWhiteboard).
• The frontend service makes a PUT request to the /api/v1/whiteboards/:whiteboardId/update endpoint.
• The backend updateWhiteboardData service method updates the corresponding fields in the Firebase database.
• Upon success, the frontend updates the Redux store, and the UI reflects the changes.

Sources: apps/portal/components/pagesComponents/_whiteboardsScreen/WhiteboardContainer/WhiteboardCard/WhiteboardCard.tsx:75-140, apps/api/src/module/whiteboards/controllers/whiteboard.controller.ts:50-61

Sharing a Whiteboard

A whiteboard can be made public, allowing anyone with the link to view it.

1. The user clicks the "Share" or "Copy Link" action on a WhiteboardCard.
2. The shareWboard function is called. If the whiteboard is not yet public (!whiteboard.isPublic), it first calls the shareWhiteboard service.
3. This triggers a PUT request to /api/v1/whiteboards/:whiteboardId/update with isPublic: true.
4. The backend updates the isPublic flag in Firebase.
5. A unique shareable link (/whiteboard/{id}?s=1) is copied to the user's clipboard.

Sources: apps/portal/components/pagesComponents/_whiteboardsScreen/WhiteboardContainer/WhiteboardCard/WhiteboardCard.tsx:99-116, apps/portal/components/pagesComponents/_whiteboardsScreen/WhiteboardModals/ShareWhiteboardModal/ShareWhiteboardModal.tsx:8-15

API Endpoints

The following table summarizes the REST API endpoints that support the Whiteboard UI. All endpoints except for get-shared require user authentication.

Method	Endpoint	Description
POST	/api/v1/whiteboards/new	Creates a new whiteboard. Requires a name query parameter.
GET	/api/v1/whiteboards/all	Fetches all whiteboards for the authenticated user.
DELETE	/api/v1/whiteboards/:whiteboardId/delete	Deletes a specific whiteboard.
PUT	/api/v1/whiteboards/:whiteboardId/update	Updates a whiteboard's properties (name, trash, favorite, isPublic).
GET	/api/v1/whiteboards/:whiteboardId/get	Fetches a specific whiteboard if the user is the owner.
GET	/api/v1/whiteboards/:whiteboardId/get-shared	Fetches a specific whiteboard if it is public (isPublic: true).

Sources: apps/api/src/module/whiteboards/controllers/whiteboard.controller.ts, apps/portal/app/services/api/whiteboards.ts