Excalidraw

# MISSION: Scaffold "Excalidraw" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Excalidraw**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Excalidraw
- **What It Does**: Excalidraw is an open-source virtual whiteboard for hand-drawn-style diagrams, shipped both as an embeddable React component on npm and as the local-first, collaborative excalidraw.com web app.
- **Domain & Category**: Canvas Editor
- **Production Scale**: 2-5 people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: A client-only canvas editor kept free of backend dependencies so it can be embedded anywhere; sharing, live collaboration and persistence are layered on in the app shell with Firebase and a Socket.IO relay.
- **Live Website Reference**: https://excalidraw.com
- **Source Repository**: https://github.com/excalidraw/excalidraw
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: React, TypeScript, Vite, Canvas API, Rough.js, Jotai, Firebase, Socket.IO, Vitest, Vercel, Docker
- **Primary Language(s)**: TypeScript
- **License of the reference repo**: MIT
- **Frontend**: React — UI shell, toolbars and menus; the drawing surface itself is rendered imperatively on a canvas.; TypeScript — Every workspace package is TypeScript; the root `test:typecheck` script runs `tsc` across the monorepo.; Canvas API — Infinite whiteboard drawn on HTML5 canvas; `canvas-roundrect-polyfill` and `points-on-curve` support the renderer.; Rough.js — Generates the hand-drawn look for every shape; `perfect-freehand` handles free-draw strokes.; Jotai — Atom-based state for the editor package and the app shell (`jotai`, `jotai-scope`, `excalidraw-app/app-jotai.ts`).; Radix UI — Accessible primitives behind menus and dialogs inside the editor package.; Vite — Builds the excalidraw.com app (`vite.config.mts`); `vite-plugin-pwa` produces the offline-capable PWA.
- **Backend & APIs**: Socket.IO — Client of a separate Socket.IO relay for live collaboration; the relay server is not part of this repository.
- **Data & persistence**: Firebase — Firestore and Firebase Storage hold shared scenes and files for links and live rooms; rules live in `firebase-project/`.; IndexedDB — Local-first persistence of the current drawing through `idb-keyval`.
- **Infrastructure & deploy**: Vercel — Hosts excalidraw.com; `vercel.json` sets `outputDirectory` to `excalidraw-app/build` and the build reads `VERCEL_GIT_COMMIT_SHA`.; Docker — Multi-stage image builds the app on Node 24 and serves the static bundle from nginx; published by `publish-docker.yml`.; Sentry — Browser error tracking in the app shell (`@sentry/browser`, `excalidraw-app/sentry.ts`).
- **Tooling, testing & ops**: Vitest — Unit and snapshot tests with canvas mocking (`vitest-canvas-mock`) and coverage in CI.; GitHub Actions — Lint, test, size-limit, Docker publish, Sentry release and npm autorelease workflows.; ESLint — Shared `@excalidraw/eslint-config` and Prettier config enforced through husky and lint-staged.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/excalidraw/excalidraw @ c0ad61c)
1. **The editor is an npm package; excalidraw.com is a thin app around it**: The yarn workspace splits `packages/excalidraw` (published as `@excalidraw/excalidraw`, a React component) from `excalidraw-app` (the excalidraw.com shell). Collaboration, sharing, analytics and persistence live only in the app, so the embeddable package stays free of backend dependencies.
2. **Rendering is imperative canvas, not DOM**: Shapes are drawn on an HTML5 canvas with Rough.js for the hand-drawn look and perfect-freehand for pen strokes. React only owns the chrome around the canvas, which keeps the editor responsive on large scenes and lets the package expose its own scene model instead of DOM nodes.
3. **Local-first by default, backend only for sharing**: The app autosaves to the browser (`idb-keyval`) and works offline as a PWA (`vite-plugin-pwa`). Firebase Firestore and Storage are used only when a user shares a link or starts a live session, and the README describes those flows as end-to-end encrypted.
4. **Collaboration is a relay, not a server-side document model**: Live sessions use `socket.io-client` to broadcast element updates through a relay; the relay server is not in this repository. Ordering of elements relies on the vendored `@excalidraw/fractional-indexing` package, which lets clients reconcile concurrent edits without a central authority.
5. **Small internal packages with an explicit build pipeline**: `packages/common`, `element`, `math`, `utils`, `laser-pointer` and `fractional-indexing` are separate workspace packages, each built to ESM by scripts in `scripts/` (`buildBase.js`, `buildPackage.js`). This keeps the public API surface of the editor package deliberate.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Utilize Vite 6 with TanStack Router for fully type-safe routing. Manage server state and caching via TanStack Query v5 with optimistic UI updates.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (Firebase, IndexedDB): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.