How vppillai/whiteboard works
1. Repository shape
This is a TypeScript monorepo with one primary product app in apps/web, a small apps/server runtime for self-hosted/container deployment, and a packages/shared package for cross-app types. The browser app is the real system; the server is an edge/deployment wrapper rather than the source of business logic.
2. Primary runtime: browser whiteboard
apps/web is the main application and is built with Vite for the browser. It owns the full interactive whiteboard experience: drawing, selecting, text editing, image paste, export, settings, persistence, and shortcuts. The architecture is strongly client-side and offline-first; there is no account/session/backend data model in the repo.
3. Bootstrap and shell
apps/web/src/main.ts is the entry point that wires together the app shell, global state, keyboard handling, theming, menus, overlays, and the canvas surface. The surrounding files in menu-*, toolmenu.ts, sidepanel.ts, popover.ts, and helpoverlay.ts are chrome/UI subsystems layered around the core canvas, not the core itself.
4. Input pipeline and tool abstraction
Pointer and keyboard input flow through a dedicated interaction layer: pointer.ts, camera.ts, pan.ts, zoomfit.ts, and viewstate.ts manage viewport and gesture state, while tools/ implements the actual tools (pen, eraser, select, shape, text, laser). The repo’s design centers on a tool abstraction: raw events are normalized, routed to the active tool, and then converted into model changes or transient preview state.
5. Document model and object stores
The whiteboard content is split into specialized stores: strokestore.ts, textstore.ts, shapestore.ts, and imagestore.ts. That separation mirrors the object types that appear on the canvas and keeps rendering, selection, export, and clipboard logic type-specific. ops.ts provides the op-based mutation layer and is the basis for undo/redo, rather than treating the document as an opaque blob.
6. Rendering pipeline
Rendering is handled in render.ts plus specialized renderers such as rendershapes.ts, rendertexts.ts, and renderimages.ts. This suggests a layered draw stack where strokes, images, shapes, and text are composited in z-order, with selection and transient tool previews drawn on top. The architecture is optimized for low-latency incremental redraws rather than document-level re-rendering.
7. Text and shape interaction
Text and shapes are first-class objects, not annotations glued onto strokes. Text uses a geometry/editing split (textgeom.ts, textstore.ts, and the tools/text.ts + settings overlays), while shapes have their own geometry and edit path (brushes.ts, imagegeom.ts, shapestore.ts, tools/shape.ts). Selection/edit handles are shared across object types but specialized by object kind.
8. Clipboard, paste, and import/export boundaries
Clipboard and import flows are significant subsystems: clipboardstrokes.ts, selectionclipboard.ts, imageclipboard.ts, imagepaste.ts, and persist-callbacks.ts coordinate structured copy/paste and browser clipboard integration. Export is similarly separated into export/png.ts, export/svg.ts, and export/pdf.ts, indicating a deliberate boundary between the editable internal model and external presentation formats.
9. Persistence and local-first storage
State persistence is handled client-side via storage.ts and IndexedDB-backed flows, with initialization/reset helpers such as firstrun.ts, factoryreset.ts, and resetflow.ts. The app is designed to resume locally without a server round-trip; persistence is about restoring the whiteboard model and user settings, not syncing to a backend.
10. Settings, theme, and UI personalization
settings.ts plus settings/ hold configurable drawing behavior such as pressure curves, swatches, grid, and theme. theme.ts, grid.ts, colorpicker.ts, swatchpalette.ts, and optionsmenu.ts show that customization is a first-class subsystem, with a dedicated side panel rather than ad hoc modal state.
11. Performance and interaction constraints
Files like metrics.ts, perftest.ts, and the ADRs indicate that low latency is a core architectural goal, especially for pen input. The design is tuned around indirect-input pen tablets: coalesced/predicted pointer events, pressure curves, and fast rendering are treated as system constraints, not polish.
12. Server and deployment boundary
apps/server is a small Bun-based service used for containerized/self-hosted deployment, paired with Docker files and deploy.sh. The repo also supports GitHub Pages via CI, which reinforces that the browser app is static or mostly static and can be shipped without a traditional application backend.
13. Shared contracts and test structure
packages/shared contains common types used across packages, keeping type contracts centralized. Tests live alongside the relevant modules in apps/web/src/*.test.ts, which implies the architecture is modular and behavior-driven at the subsystem level rather than through a single end-to-end suite.
14. Overall system diagram
A good architecture diagram would show: browser input events entering the tool layer, tools mutating the whiteboard model through ops/stores, renderers projecting that model to the canvas, and separate outbound paths for clipboard/export/persistence. The server/deployment side should be drawn as a thin delivery layer, not as part of the interaction or data model.
Main entry points: index.ts Tools · ops.ts Document model · main.ts Main shell · render.ts Renderer
Components 16
Web app
Primary browser whiteboard runtime in apps/web
- Main shell · Browser entrypoint that wires app state, keyboard handling, theming, menus, overlays, and canvas startup.
apps/web/src/main.ts - Input pipeline · Pointer, pan, zoom, camera, and view state logic that normalizes raw user input into tool-ready interactions.
apps/web/src/pointer.ts - Tools · Active tool implementations and routing for pen, eraser, select, shape, text, and laser interactions.
apps/web/src/tools/index.ts - Document model · Op-based whiteboard state and typed object stores for strokes, text, shapes, and images.
apps/web/src/ops.ts - Renderer · Canvas render pipeline that composites strokes, images, shapes, text, selection, and previews.
apps/web/src/render.ts - Clipboard · Structured clipboard, paste, and native image/selection transfer flows.
apps/web/src/selectionclipboard.ts - Export · PNG, SVG, and PDF export paths for external presentation formats.
apps/web/src/export/index.ts - Persistence · Client-side storage, first-run, reset, and persistence callback flows for local-first state recovery.
apps/web/src/storage.ts - Settings · User configuration for drawing behavior, swatches, grid, theme, and panel content.
apps/web/src/settings.ts - UI chrome · Menus, side panels, popovers, help overlay, and toolbar/pill controls around the canvas.
apps/web/src/sidepanel.ts - Images · Image cache, image geometry, paste, and clipboard handling for imported bitmap content.
apps/web/src/imagepaste.ts - Text layout · Text geometry and contenteditable overlay path used by the text tool and editor interactions.
apps/web/src/textgeom.ts - Shapes · Shape and stroke geometry plus shape store support for editable vector objects.
apps/web/src/shapestore.ts - Perf guardrails · Metrics and performance test harnesses that reflect the low-latency pen-input focus.
apps/web/src/metrics.ts
Server
Thin Bun deployment wrapper in apps/server
- Server entry · Minimal Bun runtime entrypoint for self-hosted or container deployment.
apps/server/src/index.ts
Shared
Cross-package contracts in packages/shared
- Shared types · Common TypeScript contracts shared across packages.
packages/shared/src/index.ts
Connections 23
- Main shell → Input pipeline: wires input · Bootstraps the interaction pipeline and global handlers.
- Main shell → Tools: activates · Connects the shell to the active tool system.
- Main shell → UI chrome: mounts chrome · Composes menus, overlays, and panels around the canvas.
- Main shell → Renderer: starts draw · Initializes the canvas rendering surface.
- Input pipeline → Tools: routes events · Normalizes pointer and keyboard input for the current tool.
- Tools → Document model: mutates · Tools commit document changes through ops and stores.
- Tools → Renderer: preview feedback · Tools contribute transient selection and gesture previews.
- Document model → Renderer: feeds scene · Stores provide renderable document state.
- Renderer → UI chrome: draws overlays · Selection and interaction feedback layer on top of the canvas.
- Tools → Clipboard: copy/paste · Selection and object tools participate in clipboard flows.
- Clipboard → Document model: imports objects · Clipboard and paste flows materialize document objects.
- Tools → Export: exports selection · Tool and model state are used for output rendering.
- Document model → Export: serializes · Export reads the canonical board state.
- Persistence → Document model: restores state · Persistence reloads whiteboard content and settings locally.
- Settings → UI chrome: configures panels · Preferences surface in menus, side panels, and popovers.
- Settings → Tools: tunes behavior · Tool behavior depends on user settings such as pressure and grid.
- Images → Document model: stores assets · Image import flows feed the image store and related model state.
- Text layout → Tools: supports text tool · Text editing relies on geometry and overlay-based editing.
- Shapes → Tools: supports shape tool · Shape and stroke geometry back the editable shape pipeline.
- Perf guardrails → Input pipeline: constrains latency · Performance guardrails shape input and rendering responsiveness.
- Server entry → Shared types: uses contracts · Deployment wrapper depends on shared type definitions.
- Document model → Shared types: uses contracts · Web runtime shares common types with other packages.
- Main shell → Server entry: deploys with · The browser app is delivered alongside the thin server runtime.