Nicholai/excalidraw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
excalidraw/docs/architecture/brownfield-architecture.md
nicholai 4648a77c92 bmad-init
2025-09-21 02:12:56 -06:00

7.4 KiB
Raw Blame History

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