# jitsi/excalidraw architecture

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

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

## Overview

##### Main Components

- Frontend Web Application:
– All the code lives in the “src” directory (with subdirectories like “components”, “actions”, “element”, “scene”, “renderer”, etc.) indicating a rich, component-based React app.
– “public” holds static assets (HTML, CSS, images) that bootstrap the application.
– The “dev-docs” directory and “packages” folder also show modular parts of the code (e.g., the “excalidraw” package) and documentation that inform the internal architecture.

- Collaboration Module:
– There is a dedicated subfolder “src/excalidraw-app/collab” indicating real-time and collaborative functionalities.
– The README explicitly states that for running collaboration locally, one must set up a separate “collab server” (referencing the excalidraw-room repository).

- Data and State Management:
– Multiple files under “src/actions”, “src/appState.ts”, and “src/jotai.ts” suggest that state management and event handling is modularized.
– Integration with Firebase is hinted at by the “firebase-project” directory, which holds rules and configuration files.

- External Services & Deployment Infrastructure:
– Docker-related files (Dockerfile, docker-compose.yml) and GitHub Actions workflows under “.github/workflows” demonstrate CI/CD pipelines and containerization.
– References to Vercel (deployment), Sentry (logging/monitoring), and Crowdin (localization) show integration points with external platforms.

##### Understand the Relationships and Interactions

- The browser/client (frontend) is primarily built with React and communicates with backend services:
- The UI components inside “src/components” render the whiteboard, while state changes (triggered by user actions or collaboration messages) are managed via logic in “src/actions” and state files in “src/appState.ts”.
- Real-time collaboration is achieved through web socket or signal channels that connect the client with a separate collab server.

- Data Persistence & Storage
- Although there is no dedicated backend server inside this repository, the project shows interactions with Firebase (for authentication, Firestore, or storage in “firebase-project”) and localStorage (handled in “src/excalidraw-app/data/localStorage.ts”).

- Deployment and Build Pipeline
- CI workflows, Docker configurations, and instructions for self-hosting indicate that the code moves from development (local Node.js, Docker Compose) to production (Docker images, Vercel deployments).

##### Architectural Patterns & Design Principles

- Component-Based Architecture:
– The system clearly uses React’s component structure, separating UI (views), business logic (actions/state management), and data handling.

- Modularity & Separation of Concerns:
– Code is clearly organized into modules (actions, components, packages, docs) making it easier to manage complex interactions and unit test individual parts (lots of tests in “src/tests”).

- Collaboration & Real-time Data Flow:
– The design shows a separation between the local drawing state and the real-time collaboration layer (handled in “src/excalidraw-app/collab”), which is isolated for easier scaling/replacement.

- Clear labels for each component of the system.
- Data flow from user interactions (UI components) → action dispatches/state updates.
- Interaction between client and external collab server.
- Synchronization with Firebase/local storage.
- Frontend components versus external services and deployment pipelines.
- Modular code areas (such as “actions”, “components”, “collab”) which interact with one another.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external

    subgraph "Client (Browser/Frontend)"
        SA["Static Assets"]:::client
        UIC["UI Components"]:::client
        SM["State Management"]:::action
        RS["Rendering & Scene"]:::client
        MD["Modular & Docs"]:::client
    end

    subgraph "Real-Time Collaboration"
        CM["Collaboration Module"]:::collab
    end

    subgraph "Data & Persistence"
        LS["Local Storage"]:::data
        DM["Data Modules"]:::data
        FI["Firebase Integration"]:::external
    end

    subgraph "Deployment & Build"
        CI["CI/CD Pipeline"]:::deployment
        DC["Docker Config"]:::deployment
        EI["External Integrations"]:::deployment
        DEP["Deployment Config"]:::deployment
    end

    %% Connections
    User -->|"interacts"| SA
    SA -->|"loads"| UIC
    UIC -->|"updates"| SM
    SM -->|"renders"| RS
    UIC <==>|"communicates"| CM
    CM -->|"updates"| SM
    SM -->|"persists"| LS
    SM -->|"manages"| DM
    SM -->|"syncs"| FI
    CI -->|"builds"| DC
    DC -->|"deploys"| DEP
    CI -->|"integrates"| EI

    %% Click Events
    click SA "https://github.com/jitsi/excalidraw/tree/master/public"
    click UIC "https://github.com/jitsi/excalidraw/tree/master/src/components"
    click SM "https://github.com/jitsi/excalidraw/tree/master/src/actions"
    click RS "https://github.com/jitsi/excalidraw/tree/master/src/renderer"
    click MD "https://github.com/jitsi/excalidraw/tree/master/src/packages"
    click CM "https://github.com/jitsi/excalidraw/tree/master/src/excalidraw-app/collab"
    click LS "https://github.com/jitsi/excalidraw/blob/master/src/excalidraw-app/data/localStorage.ts"
    click DM "https://github.com/jitsi/excalidraw/tree/master/src/data"
    click FI "https://github.com/jitsi/excalidraw/tree/master/firebase-project"
    click DC "https://github.com/jitsi/excalidraw/tree/master/Dockerfile"
    click CI "https://github.com/jitsi/excalidraw/tree/master/.github/workflows"
    click EI "https://github.com/jitsi/excalidraw/blob/master/crowdin.yml"
    click DEP "https://github.com/jitsi/excalidraw/blob/master/vercel.json"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef action fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef collab fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef data fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef deployment fill:#F5CBA7,stroke:#943126,stroke-width:2px;
```
