# DeckTools Whiteboard — Complete Technical & Functional Specification

Website: https://whiteboard.decktools.app
Platform: Progressive Web Application (PWA) / Static Canvas Frontend with PHP/MySQL Backend
Audience: Educators, Students, Remote Teams, Developers, AI Agents

---

## 1. Architectural Overview
DeckTools Whiteboard is built on high-performance HTML5 Canvas rendering paired with Rough.js. It features a reactive decoupled modular architecture:
- `js/render.js`: Double-buffered canvas graphics pipeline with DPR scaling, world-to-screen transforms, grid rendering, selection bounds, and live cursor indicators.
- `js/tools.js`: Pointer event pipeline handling pointerdown, pointermove, pointerup, pinch-to-zoom gestures, shape construction, and cursor resizing.
- `js/objects.js`: Mathematical models, AABB collision detection, hit-testing, z-ordering, grouping, alignment, distribution, and geometric transformations.
- `js/text.js`: Inline rich text engine supporting multi-span styling (fonts, colors, size, bold, italic, underline) and contenteditable overlays.
- `js/api.js`: Multi-client communication engine managing WebSocket/HTTP sync, client-id generation in sessionStorage, heartbeat telemetry, and event queue polling.
- `js/state.js`: Central state machine with independent per-tool configuration profiles, undo/redo history stacks, and board management.
- `js/storage.js`: Offline-first IndexedDB storage with automatic TTL expiry enforcement (24h default scratchpad) and permanent lesson archiving.
- `server.js` & `api/sync.php`: Backend synchronization engines supporting MySQL persistence, room admission control, 15-user limits, and event streaming.

---

## 2. Tools & Capabilities

### Freehand Ink & Drawing
| Tool | Shortcut | Description |
|------|----------|-------------|
| Pencil | P | Excalidraw-style Rough.js handwriting with organic stroke variation, bowing, and roughness |
| Pen | B | Ultra-smooth vector ink with multi-pass Bezier curve smoothing |
| Marker | M | Thick felt-tip marker with rounded caps and high opacity |
| Highlighter | G | Translucent broad highlighter that preserves underlying text readability |
| Brush | U | Artistic brush stroke with pressure-sensitive width dynamics |
| Eraser | E | Precision sub-path stroke eraser that divides ink strokes at contact points |
| Object Eraser | Shift+E | Deletes entire shapes and strokes on contact |

### Geometry & Connectors
| Tool | Shortcut | Description |
|------|----------|-------------|
| Rectangle | R | Box with optional rounded corners and solid/rough fill |
| Ellipse | O | Perfect circles and ovals with Rough.js hand-drawn styling |
| Triangle | T | Equilateral and custom triangular polygons |
| Star | S | Multi-pointed star shape with customizable outer/inner radii |
| Polygon | Y | Regular N-sided polygon or freeform multi-click polygon tool |
| Straight Line | L | Precision vector line with solid, dashed, or dotted stroke |
| Arrow | A | Directional vector arrow with proportional arrowhead geometry |
| Double Arrow | Shift+A | Dual-ended arrow for representing relationships and dimensions |
| Curve | C | Smooth 3-point quadratic Bezier curve with draggable control point |
| Connector | W | Smart connector that automatically snaps to anchors (N, S, E, W, corners) on shapes |

### Content & Teaching Tools
| Tool | Shortcut | Description |
|------|----------|-------------|
| Text | X | Typography box with cursor-based drag resizing, custom fonts, and span formatting |
| Sticky Note | N | Digital sticky note in pastel colors (yellow, blue, green, pink, purple) |
| Image | I | Local and web image import with inline cropping, aspect ratio locking, and rotation |
| Table | Shift+T | Interactive data grid table with customizable rows, columns, and CSV export |
| Equation | Q | LaTeX mathematical formula renderer powered by KaTeX SVG rendering |
| Mindmap | K | Interactive radial mind map tree with auto-branching child nodes |
| Laser | Z | Presentation laser pointer with trailing fade-out glowing trail |
| Ruler | D | Draggable pixel/millimeter measurement guide |
| Protractor | F | 360-degree interactive geometric angle measuring widget |
| Compass | J | Compass tool for constructing geometric arcs and circles |

---

## 3. Real-Time Collaboration & Room Security

### Virtual Classroom Rooms
- **URL Parameter**: Entering `https://whiteboard.decktools.app/?room=[ROOM_CODE]` immediately connects to the room.
- **Room Sanitization**: Room codes automatically strip extraneous trailing strings or pasted invitation tokens.
- **Mandatory Password**: All collaborative rooms require a host-defined password. Unauthorized attempts return HTTP 403.
- **Room Capacity**: Strict maximum of 15 simultaneous live participants per room to guarantee low latency. Attempts beyond 15 return HTTP 429.

### Teacher Moderation & Sub-User Workflow
1. **Waiting Room**: When a student enters a room with the correct password, they enter a waiting lobby (`status: pending`).
2. **Host Admission**: The host receives a notification with `Admit` or `Decline` buttons. The host can also toggle `Access Everyone` (auto-admit).
3. **Student Submission Queue**: In live sessions, student drawings appear on the teacher's board marked as `⏳ Pending Approval`.
4. **Publish / Reject**: The teacher can click `Approve` (or `Approve All`) to publish the drawing to the entire class, or `Reject` to clear it.
5. **No Refresh Real-Time Sync**: Changes sync within 400ms across all participants without requiring page reloads.

---

## 4. API Endpoints Reference
Base URL: `/api/` (PHP / MySQL) or root endpoints (Node.js)

- `GET /api/status.php`: Health check returning system status, time, and database connectivity.
- `POST /api/sync.php?action=join`: Authenticates user into room.
  - Request body: `{ roomCode, clientId, userName, userColor, password, isHost, autoAdmit }`
  - Response: `{ ok: true, role: 'host'|'participant', status: 'approved'|'pending', autoAdmit }`
- `POST /api/sync.php?action=heartbeat`: Telemetry and cursor position streaming.
  - Request body: `{ roomCode, clientId, x, y, tool }`
  - Response: `{ ok: true, collaborators: [...], waitingUsers: [...] }`
- `POST /api/sync.php?action=broadcast`: Dispatches drawing events (`add_object`, `update_objects`, `delete_objects`, `clear_ink`, `clear_page`, `student_submission`, `approve_submission`).
- `GET /api/sync.php?action=poll&room_code=[CODE]&client_id=[ID]&last_id=[INT]`: Event stream poll.
- `POST /api/boards.php?action=save`: Persists entire board document to MySQL database.
- `GET /api/boards.php?action=get&id=[BOARD_ID]`: Retrieves board document.
- `GET /api/boards.php?action=list`: Lists saved boards for current client.

---

## 5. Keyboard Shortcuts
- `V`: Select & Transform
- `H`: Hand / Pan Canvas
- `P`: Pencil (Rough.js handwriting)
- `B`: Pen (Smooth vector ink)
- `E`: Eraser
- `Shift+E`: Whole Object Eraser
- `R`: Rectangle
- `O`: Ellipse / Circle
- `L`: Line
- `A`: Arrow
- `X`: Text Box
- `N`: Sticky Note
- `Ctrl+Z`: Undo
- `Ctrl+Y` / `Ctrl+Shift+Z`: Redo
- `Ctrl+0` / `0`: Fit to screen
- `Ctrl++` / `Ctrl+-`: Zoom in / Zoom out
- `Delete` / `Backspace`: Remove selected objects
- `Space + Drag`: Pan canvas freely