# hea7hen/excalidraw architecture

> Architecture diagram of the GitHub repository hea7hen/excalidraw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hea7hen/excalidraw
- Repository: https://github.com/hea7hen/excalidraw

## Overview

##### Main Components
- Core Drawing Library (packages/excalidraw): The heart of the engine containing the rendering logic, element data structures, undo/redo, transformation, and overall editor state. This package encapsulates the main logic to create and manipulate whiteboard drawings.
- Utility Modules and Math Library (packages/math, packages/utils): These support geometrical operations, calculations, collision detection, and general helper functions needed by the core library.
- Documentation and Examples (dev-docs, examples): Although not part of the runtime architecture, these help understand intended usage and integration patterns. They can be sketched on the side as “supporting artifacts” that guide developers.
- Build, Testing, and Deployment Infrastructure: Note the presence of Docker files, GitHub workflows, scripts for building locales, version handling, etc. These are part of the CI/CD and development environment.
- External Integrations and Services: There is evidence of Firebase integration (in data/firebase.ts) for real-time collaboration, end-to-end encryption, and possible error reporting via Sentry. Also note integrations with external hosting and deployment tools (e.g., Vercel) seen in configuration files and the README.

##### Depicting Relationships and Data Flow
- Flow from user interactions (e.g., drawing, tool selection) to the core engine processing these inputs and updating state.
- Optionally, illustrate how build tools, deployment pipelines, and testing scripts (CI/CD from .github/workflows, Dockerfiles, etc.) integrate with the overall project, albeit being separated from runtime components.

##### Architectural Patterns and Design Principles
- Modular Structure: Emphasize the separation into core logic (drawing functionalities), UI presentation (React components in excalidraw-app), and service integration (collaboration, analytics, etc.).
- Client-First Architecture: Being a browser-based interactive whiteboard, most processing happens client side. The collaboration module connects to remote services to persist or share state.
- Layered Abstraction: The UI layer is decoupled from the drawing engine, and the engine itself is built on top of a collection of utility and math functions.

##### Final Checklist for the Principal Software Engineer
- Maintain clarity and readability by grouping related components (e.g., all components under “excalidraw-app” should be grouped as the presentation layer).
- Keep annotations minimal but insightful so that any new reader can grasp how the open-source Excalidraw system is constructed and how its various modules interact.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser Client"
        UI["Excalidraw App – UI Components"]:::frontend
    end

    subgraph "Core Modules"
        Engine["Core Drawing Engine"]:::core
        Math["Math Library"]:::library
        Utils["Utility Library"]:::library
    end

    subgraph "External Integrations"
        Firebase["Firebase Integration"]:::integration
        Sentry["Sentry Integration"]:::integration
    end

    subgraph "Supporting Artifacts"
        Docs["Documentation"]:::supporting
        Examples["Examples"]:::supporting
    end

    subgraph "Infrastructure & CI/CD"
        CICD["CI/CD & Build Tools"]:::infrastructure
    end

    UI -->|"triggers"| Engine
    Engine -->|"utilizes"| Math
    Engine -->|"utilizes"| Utils
    UI <-->|"syncs"| Firebase
    UI -->|"reports"| Sentry
    CICD -->|"builds&deploys"| UI
    CICD -->|"builds&deploys"| Engine
    CICD -->|"runs"| Docs

    click UI "https://github.com/hea7hen/excalidraw/tree/master/excalidraw-app/"
    click Engine "https://github.com/hea7hen/excalidraw/tree/master/packages/excalidraw/"
    click Math "https://github.com/hea7hen/excalidraw/tree/master/packages/math/"
    click Utils "https://github.com/hea7hen/excalidraw/tree/master/packages/utils/"
    click Docs "https://github.com/hea7hen/excalidraw/tree/master/dev-docs/"
    click Examples "https://github.com/hea7hen/excalidraw/tree/master/examples/"
    click CICD "https://github.com/hea7hen/excalidraw/tree/master/.github/workflows/"
    click Firebase "https://github.com/hea7hen/excalidraw/blob/master/excalidraw-app/data/firebase.ts"
    click Sentry "https://github.com/hea7hen/excalidraw/blob/master/excalidraw-app/sentry.ts"

    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#FFE4B5,stroke:#000,stroke-width:2px;
    classDef library fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef integration fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef supporting fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef infrastructure fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
