169 lines
7.4 KiB
Markdown
169 lines
7.4 KiB
Markdown
# Excalidraw Monorepo Brownfield Architecture Document
|
||
|
||
## Introduction
|
||
|
||
This document captures the current state of the Excalidraw monorepo as it exists in this workspace. It reflects real implementation details, tooling, and integration constraints to help contributors—human or AI—navigate and extend the project effectively.
|
||
|
||
### Document Scope
|
||
|
||
Comprehensive documentation of the entire repository (no PRD provided).
|
||
|
||
### Change Log
|
||
|
||
| Date | Version | Description | Author |
|
||
| ---- | ------- | ----------- | ------ |
|
||
| 2025-09-21 | 1.0 | Initial brownfield analysis | BMad Master |
|
||
|
||
## Quick Reference — Key Files and Entry Points
|
||
|
||
- Monorepo root: `package.json` (Yarn workspaces), `yarn.lock`
|
||
- App (website): `excalidraw-app/index.tsx`, `excalidraw-app/vite.config.mts`, `excalidraw-app/index.html`
|
||
- Core packages: `packages/excalidraw`, `packages/element`, `packages/common`, `packages/math`, `packages/utils`
|
||
- Tests setup: `setupTests.ts`, `vitest.config.mts`
|
||
- CI/CD: `.github/workflows/*.yml`
|
||
- Env samples: `.env.development`, `.env.production`
|
||
|
||
## High Level Architecture
|
||
|
||
### Technical Summary
|
||
|
||
- Type: JavaScript/TypeScript monorepo using Yarn v1 workspaces
|
||
- Frontend build: Vite 5 + React + TypeScript
|
||
- Test runner: Vitest 3 with JSDOM; ESLint + Prettier for lint/format
|
||
- Packages: modularized core editor (`@excalidraw/excalidraw`) plus supporting libraries
|
||
- App: a Vite-powered web app in `excalidraw-app` consuming local packages
|
||
- Examples: Next.js examples under `examples/*`
|
||
|
||
### Actual Tech Stack (from package manifests)
|
||
|
||
| Category | Technology | Version/Notes |
|
||
| --------- | ------------------ | ------------- |
|
||
| Runtime | Node.js | 18–22 supported (engines) |
|
||
| Package | Yarn | 1.x workspaces |
|
||
| Build | Vite | 5.x |
|
||
| Lang | TypeScript | 4.9.x (root) |
|
||
| UI | React | 18/19 types present |
|
||
| Testing | Vitest + jsdom | Vitest 3.x, jsdom 22 |
|
||
| Lint/Format | ESLint + Prettier | Custom configs via `@excalidraw/*` |
|
||
| CI/CD | GitHub Actions | Lint, build, release, docker, Sentry |
|
||
|
||
### Repository Structure Reality Check
|
||
|
||
```
|
||
excalidraw/
|
||
├─ excalidraw-app/ # Vite web app (entry point + hosting shell)
|
||
├─ packages/ # Core libraries (editor & utilities)
|
||
│ ├─ excalidraw/ # @excalidraw/excalidraw (main editor package)
|
||
│ ├─ element/ # Geometry & elements logic
|
||
│ ├─ common/ # Shared code
|
||
│ ├─ math/ # Math helpers
|
||
│ └─ utils/ # Misc utilities
|
||
├─ examples/ # Integration examples (incl. Next.js)
|
||
├─ dev-docs/ # Developer docs (Docusaurus content)
|
||
├─ scripts/ # Build/maintenance scripts
|
||
├─ setupTests.ts # Global test setup for Vitest/JSDOM
|
||
├─ vitest.config.mts # Vitest configuration
|
||
└─ .github/workflows/ # CI/CD workflows
|
||
```
|
||
|
||
Monorepo orchestration is defined in root `package.json` under `workspaces`.
|
||
|
||
## Source Tree and Module Organization
|
||
|
||
### `excalidraw-app` (Web App)
|
||
|
||
- Purpose: Hosts the editor UI and app shell, builds via Vite.
|
||
- Key files:
|
||
- `index.tsx` — app entry; sets `window.__EXCALIDRAW_SHA__` from env
|
||
- `App.tsx` — main UI composition and routes
|
||
- `vite.config.mts` — dev server config; overlays; PWA toggle; ESLint toggle
|
||
- `sentry.ts` — Sentry init gated by `VITE_APP_DISABLE_SENTRY`
|
||
- `index.html` — sets `window.EXCALIDRAW_ASSET_PATH`; EJS-processed by Vite
|
||
- Notable env vars (from usage and `vite-env.d.ts`):
|
||
- `VITE_APP_PORT` (dev server port)
|
||
- `VITE_APP_BACKEND_V2_GET_URL`, `VITE_APP_BACKEND_V2_POST_URL`
|
||
- `VITE_APP_WS_SERVER_URL` (collab WebSocket)
|
||
- `VITE_APP_AI_BACKEND`
|
||
- `VITE_APP_FIREBASE_CONFIG`
|
||
- `VITE_APP_DISABLE_SENTRY`, `VITE_APP_DEV_DISABLE_LIVE_RELOAD`
|
||
- `VITE_APP_ENABLE_PWA`, `VITE_APP_ENABLE_ESLINT`, `VITE_APP_COLLAPSE_OVERLAY`
|
||
- `VITE_APP_PLUS_APP`, `VITE_APP_PLUS_LP`, `VITE_APP_GIT_SHA`, `VITE_APP_PLUS_EXPORT_PUBLIC_KEY`
|
||
|
||
### `packages` (Core Libraries)
|
||
|
||
- `packages/excalidraw`: Primary editor package exported for embedding.
|
||
- `packages/element`: Element geometry/topology, elbow arrows, delta calc, etc.
|
||
- `packages/common`: Shared types/utilities across packages.
|
||
- `packages/math`: Math primitives and helpers.
|
||
- `packages/utils`: Small helpers and shared utilities.
|
||
|
||
The app depends on these via Yarn workspaces. Build order is orchestrated by root scripts (`build:packages` → common, math, element, excalidraw).
|
||
|
||
### `examples`
|
||
|
||
- Contains Next.js integrations for both Pages and App Router. Demonstrates dynamic import of the editor and asset path configuration.
|
||
|
||
## Build, Test, and Scripts
|
||
|
||
### Root Scripts (selected)
|
||
|
||
- `start` — runs `excalidraw-app` dev server
|
||
- `build` — builds the app; `build:packages` builds core libs (ES modules)
|
||
- `test` — runs Vitest; `test:code` runs ESLint; `test:typecheck` runs `tsc`
|
||
- `fix` — Prettier write + ESLint fix
|
||
|
||
### App Scripts (selected)
|
||
|
||
- `excalidraw-app/package.json` includes:
|
||
- `build:app` — Vite build with tracking and git SHA
|
||
- `build:app:docker` — Vite production build with Sentry disabled
|
||
|
||
### Testing
|
||
|
||
- Runner: Vitest (jsdom environment) configured via `vitest.config.mts`
|
||
- Global setup: `setupTests.ts` loads `vitest-canvas-mock`, `@testing-library/jest-dom`
|
||
- Coverage: `vitest --coverage` available; UI viewer via `vitest --ui`
|
||
|
||
## Configuration, Environments, and Secrets
|
||
|
||
- Local env files: `.env.development`, `.env.production` (checked in)
|
||
- `excalidraw-app/vite-env.d.ts` documents required env variables
|
||
- Sentry: Controlled via `VITE_APP_DISABLE_SENTRY` and CI workflow that proposes releases
|
||
- Firebase: Config passed via `VITE_APP_FIREBASE_CONFIG` (JSON string)
|
||
- Collab: WebSocket server URL via `VITE_APP_WS_SERVER_URL`. There are references to an external collab server (see `excalidraw-room`).
|
||
|
||
## CI/CD
|
||
|
||
- GitHub Actions flows for lint, typecheck, building Docker images, Sentry release creation, and semantic PR checks. Release flow triggers on `release` branch.
|
||
|
||
## Integration Points and External Services
|
||
|
||
- Collab server: Socket.IO client connects to `VITE_APP_WS_SERVER_URL`
|
||
- Backend v2 endpoints: `VITE_APP_BACKEND_V2_GET_URL` / `POST_URL`
|
||
- Firebase: optional feature set controlled by env
|
||
- Excalidraw Plus: multiple envs (`VITE_APP_PLUS_*`) for integration links and export
|
||
|
||
## Technical Debt and Known Issues (Observed)
|
||
|
||
- Mixed dependency ranges across packages; TypeScript 4.9.x while React type packages indicate React 19 types — verify compatibility and upgrade plan.
|
||
- Yarn v1 workspaces remain standard but consider migration path (e.g., to pnpm) only if beneficial; not required.
|
||
- Multiple env flags influence dev ergonomics (lint, PWA, live reload) — ensure CI parity to avoid config drift.
|
||
- Collab/room server not part of this repo; local development requires running it separately (see dev docs references).
|
||
|
||
## Developer Workflow Tips
|
||
|
||
1. Install: `yarn install`
|
||
2. Start dev: `yarn start` (Vite dev server for `excalidraw-app`)
|
||
3. Build libs: `yarn build:packages`
|
||
4. Build app: `yarn build`
|
||
5. Tests: `yarn test:all` or `yarn test`
|
||
|
||
## Appendix: Notable Files
|
||
|
||
- Root `package.json`: workspaces, scripts, engines
|
||
- `excalidraw-app/index.tsx`, `App.tsx`: application composition
|
||
- `excalidraw-app/vite.config.mts`: server/overlay/PWA controls
|
||
- `setupTests.ts`, `vitest.config.mts`: test setup
|
||
- `.github/workflows/*`: CI jobs for lint, build, release, docker, Sentry
|
||
|