# vppillai/whiteboard architecture

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

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

## Overview

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: [`apps/web/src/tools/index.ts`](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/tools/index.ts) (Tools), [`apps/web/src/ops.ts`](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/ops.ts) (Document model), [`apps/web/src/main.ts`](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/main.ts) (Main shell), [`apps/web/src/render.ts`](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/render.ts) (Renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_web_main["Main shell<br/>bootstrap/ui<br/>[main.ts]"]
  node_web_input["Input pipeline<br/>interaction<br/>[pointer.ts]"]
  node_web_tools["Tools<br/>tool system<br/>[index.ts]"]
  node_web_model["Document model<br/>ops/stores<br/>[ops.ts]"]
  node_web_render["Renderer<br/>draw pipeline<br/>[render.ts]"]
  node_web_clipboard["Clipboard<br/>copy/paste"]
  node_web_export["Export<br/>output<br/>[index.ts]"]
  node_web_persist["Persistence<br/>local storage<br/>[storage.ts]"]
  node_web_settings["Settings<br/>preferences<br/>[settings.ts]"]
  node_web_ui["UI chrome<br/>shell/ui<br/>[sidepanel.ts]"]
  node_web_images["Images<br/>asset flow<br/>[imagepaste.ts]"]
  node_web_text["Text layout<br/>editing<br/>[textgeom.ts]"]
  node_web_shapes["Shapes<br/>geometry<br/>[shapestore.ts]"]
  node_web_perf["Perf guardrails<br/>latency<br/>[metrics.ts]"]
end

subgraph group_server["Server"]
  node_server_entry["Server entry<br/>bun service<br/>[index.ts]"]
end

subgraph group_shared["Shared"]
  node_shared_types["Shared types<br/>contracts<br/>[index.ts]"]
end

node_web_main -->|"wires input"| node_web_input
node_web_main -->|"activates"| node_web_tools
node_web_main -->|"mounts chrome"| node_web_ui
node_web_main -->|"starts draw"| node_web_render
node_web_input -->|"routes events"| node_web_tools
node_web_tools -->|"mutates"| node_web_model
node_web_tools -->|"preview feedback"| node_web_render
node_web_model -->|"feeds scene"| node_web_render
node_web_render -->|"draws overlays"| node_web_ui
node_web_tools -->|"copy/paste"| node_web_clipboard
node_web_clipboard -->|"imports objects"| node_web_model
node_web_tools -->|"exports selection"| node_web_export
node_web_model -->|"serializes"| node_web_export
node_web_persist -->|"restores state"| node_web_model
node_web_settings -->|"configures panels"| node_web_ui
node_web_settings -->|"tunes behavior"| node_web_tools
node_web_images -->|"stores assets"| node_web_model
node_web_text -->|"supports text tool"| node_web_tools
node_web_shapes -->|"supports shape tool"| node_web_tools
node_web_perf -->|"constrains latency"| node_web_input
node_server_entry -->|"uses contracts"| node_shared_types
node_web_model -->|"uses contracts"| node_shared_types
node_web_main -.->|"deploys with"| node_server_entry

click node_web_main "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/main.ts"
click node_web_input "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/pointer.ts"
click node_web_tools "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/tools/index.ts"
click node_web_model "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/ops.ts"
click node_web_render "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/render.ts"
click node_web_clipboard "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/selectionclipboard.ts"
click node_web_export "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/export/index.ts"
click node_web_persist "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/storage.ts"
click node_web_settings "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/settings.ts"
click node_web_ui "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/sidepanel.ts"
click node_web_images "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/imagepaste.ts"
click node_web_text "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/textgeom.ts"
click node_web_shapes "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/shapestore.ts"
click node_web_perf "https://github.com/vppillai/whiteboard/blob/main/apps/web/src/metrics.ts"
click node_server_entry "https://github.com/vppillai/whiteboard/blob/main/apps/server/src/index.ts"
click node_shared_types "https://github.com/vppillai/whiteboard/blob/main/packages/shared/src/index.ts"

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_web_main,node_web_input,node_web_tools,node_web_model,node_web_render,node_web_clipboard,node_web_export,node_web_persist,node_web_settings,node_web_ui,node_web_images,node_web_text,node_web_shapes,node_web_perf toneBlue
class node_server_entry toneAmber
class node_shared_types toneMint
```

## Components

### Web app

Primary browser whiteboard runtime in apps/web

- [Main shell](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/main.ts): bootstrap/ui · Browser entrypoint that wires app state, keyboard handling, theming, menus, overlays, and canvas startup. · `apps/web/src/main.ts`
- [Input pipeline](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/pointer.ts): interaction · Pointer, pan, zoom, camera, and view state logic that normalizes raw user input into tool-ready interactions. · `apps/web/src/pointer.ts`
- [Tools](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/tools/index.ts): tool system · Active tool implementations and routing for pen, eraser, select, shape, text, and laser interactions. · `apps/web/src/tools/index.ts`
- [Document model](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/ops.ts): ops/stores · Op-based whiteboard state and typed object stores for strokes, text, shapes, and images. · `apps/web/src/ops.ts`
- [Renderer](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/render.ts): draw pipeline · Canvas render pipeline that composites strokes, images, shapes, text, selection, and previews. · `apps/web/src/render.ts`
- [Clipboard](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/selectionclipboard.ts): copy/paste · Structured clipboard, paste, and native image/selection transfer flows. · `apps/web/src/selectionclipboard.ts`
- [Export](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/export/index.ts): output · PNG, SVG, and PDF export paths for external presentation formats. · `apps/web/src/export/index.ts`
- [Persistence](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/storage.ts): local storage · Client-side storage, first-run, reset, and persistence callback flows for local-first state recovery. · `apps/web/src/storage.ts`
- [Settings](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/settings.ts): preferences · User configuration for drawing behavior, swatches, grid, theme, and panel content. · `apps/web/src/settings.ts`
- [UI chrome](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/sidepanel.ts): shell/ui · Menus, side panels, popovers, help overlay, and toolbar/pill controls around the canvas. · `apps/web/src/sidepanel.ts`
- [Images](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/imagepaste.ts): asset flow · Image cache, image geometry, paste, and clipboard handling for imported bitmap content. · `apps/web/src/imagepaste.ts`
- [Text layout](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/textgeom.ts): editing · Text geometry and contenteditable overlay path used by the text tool and editor interactions. · `apps/web/src/textgeom.ts`
- [Shapes](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/shapestore.ts): geometry · Shape and stroke geometry plus shape store support for editable vector objects. · `apps/web/src/shapestore.ts`
- [Perf guardrails](https://github.com/vppillai/whiteboard/blob/main/apps/web/src/metrics.ts): latency · 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](https://github.com/vppillai/whiteboard/blob/main/apps/server/src/index.ts): bun service · Minimal Bun runtime entrypoint for self-hosted or container deployment. · `apps/server/src/index.ts`

### Shared

Cross-package contracts in packages/shared

- [Shared types](https://github.com/vppillai/whiteboard/blob/main/packages/shared/src/index.ts): contracts · Common TypeScript contracts shared across packages. · `packages/shared/src/index.ts`

## Connections

- 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.
