# mapbox/mapbox-gl-draw architecture

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

- Interactive diagram: https://gitdiagram.com/mapbox/mapbox-gl-draw
- Repository: https://github.com/mapbox/mapbox-gl-draw

## Overview

##### Main Components
- API & Core: At the heart of the library, you have the core API (src/api.js) that provides methods to interact with drawing features. This should be shown as the central entry point.
- Modes: The “modes” directory (src/modes) holds different drawing modes such as draw_line_string, draw_point, draw_polygon, direct_select, and simple_select. Each mode implements a specific interaction pattern with the map.
- Feature Types: The definitions for different geometry types (in src/feature_types) such as point, line_string, polygon, and multi_feature highlight the data models that the library works with.
- Event Handling & Utilities: Several files in src (e.g., events.js, mode_handler.js) and in src/lib contain functions and helpers for handling mouse events, calculating distances, managing feature movement, and creating vertices. These should be depicted as a supporting layer, providing key functionalities to the core and modes.
- Rendering & Setup: Components like src/render.js, src/setup.js, and src/ui.js deal with rendering visuals on the map and integrating with the UI layer.
- Build and Testing Infrastructure: Directories such as “bench,” “debug,” “test,” and config files like rollup.config.js indicate the robust testing and build pipelines. These may be depicted as external tools or support systems that ensure quality assurance.

##### Relationships and Interactions
- The main API connects to external applications—integrating with mapbox-gl—and uses event handling to forward user inputs to the correct mode.
- Modes communicate with the core API. Each mode (draw_point, draw_polygon, etc.) will rely on the helper methods from the “lib” directory to manage geometry operations.
- Feature types are used by both the API and modes to structure the drawn geometries, maintaining consistency between user actions and internal data representations.
- Rendering and UI modules tie in with the drawing modes to update the visual elements on the map as users interact.
- Testing and benchmarking components are external to the main execution flow but ensure the individual modules work correctly and perform well.

##### Architectural Patterns and Design Principles
- Modular Design: The code is clearly split into modular components (API, modes, features, utilities) that can be developed and tested independently.
- Separation of Concerns: Different parts of the system handle specific responsibilities (e.g., event processing separate from rendering and mode implementations).
- Extensibility: The design facilitates adding custom modes (as indicated by the README’s custom mode guidelines) by following a consistent interface (mode_interface.js).

##### Essential Architectural Elements
- That every module’s role is represented and that interactions are mapped.
- Overall flow: User initiates an action → Event handling → Mode processing (including selection, creation, editing) → Updates to Feature Models → Rendering/UI update.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependency
    EX["mapbox-gl-js"]:::external

    %% API & Core
    subgraph "API & Core"
        A1["Core API"]:::api
        A2["Setup Module"]:::api
    end
    EX -->|"integrates"| A1
    A1 -->|"initializes"| A2

    %% Event Handling & Utilities
    subgraph "Event Handling & Utilities"
        E1["Event Handling"]:::utility
        E2["Utilities"]:::utility
    end
    A1 -->|"triggers"| E1
    E2 -->|"supports"| E1

    %% Drawing Modes
    subgraph "Drawing Modes"
        M1["Draw Point"]:::mode
        M2["Draw Line String"]:::mode
        M3["Draw Polygon"]:::mode
        M4["Direct Select"]:::mode
        M5["Simple Select"]:::mode
    end
    E1 -->|"activates"| M1
    E1 -->|"activates"| M2
    E1 -->|"activates"| M3
    E1 -->|"activates"| M4
    E1 -->|"activates"| M5

    %% Feature Types
    subgraph "Feature Types"
        F1["Point"]:::feature
        F2["Line String"]:::feature
        F3["Polygon"]:::feature
        F4["Multi Feature"]:::feature
        F5["Feature"]:::feature
    end
    M1 -->|"updates"| F1
    M2 -->|"updates"| F2
    M3 -->|"updates"| F3
    M4 -->|"updates"| F4
    M5 -->|"updates"| F5

    %% Rendering & UI
    subgraph "Rendering & UI"
        R1["Rendering"]:::render
        R2["UI"]:::render
    end
    M1 -->|"triggers"| R1
    M2 -->|"triggers"| R1
    M3 -->|"triggers"| R1
    M4 -->|"triggers"| R1
    M5 -->|"triggers"| R1
    M1 -->|"updates"| R2
    M2 -->|"updates"| R2
    M3 -->|"updates"| R2
    M4 -->|"updates"| R2
    M5 -->|"updates"| R2

    %% Build and Testing Infrastructure
    subgraph "Build & Testing Infrastructure"
        B1["Bench"]:::build
        B2["Test"]:::build
        B3["Rollup Config"]:::build
    end

    %% Click Events
    click A1 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/api.js"
    click A2 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/setup.js"
    click E1 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/events.js"
    click E2 "https://github.com/mapbox/mapbox-gl-draw/tree/main/src/lib"
    click M1 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/modes/draw_point.js"
    click M2 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/modes/draw_line_string.js"
    click M3 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/modes/draw_polygon.js"
    click M4 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/modes/direct_select.js"
    click M5 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/modes/simple_select.js"
    click F1 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/feature_types/point.js"
    click F2 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/feature_types/line_string.js"
    click F3 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/feature_types/polygon.js"
    click F4 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/feature_types/multi_feature.js"
    click F5 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/feature_types/feature.js"
    click R1 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/render.js"
    click R2 "https://github.com/mapbox/mapbox-gl-draw/blob/main/src/ui.js"
    click B1 "https://github.com/mapbox/mapbox-gl-draw/tree/main/bench"
    click B2 "https://github.com/mapbox/mapbox-gl-draw/tree/main/test"
    click B3 "https://github.com/mapbox/mapbox-gl-draw/blob/main/rollup.config.js"

    %% Styles
    classDef api fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef mode fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef feature fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef utility fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef render fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef build fill:#e2d4f3,stroke:#8e44ad,stroke-width:2px;
```
