# fastmail/squire architecture

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

- Interactive diagram: https://gitdiagram.com/fastmail/squire
- Repository: https://github.com/fastmail/squire

## Overview

##### Main Components

a) Core Editor Component:
- Central component representing the Squire editor instance
- Should show integration with DOM and event handling
- HTML-centric nature of the editor

b) Module Organization:
- Keyboard Handling Module
- Node Management Module
- Range Management Module
- Clipboard Module
- Clean/Sanitization Module

##### Architectural Patterns

- Event-driven architecture (shown by the extensive event system)
- DOM manipulation patterns
- HTML as source-of-truth (unlike other editors that use different data models)

##### Detailed Component Breakdown

Core Editor:

- Squire Editor    |

- DOM Integration     |
- Event System        |
- HTML Management     |
- Selection Handling  |
- Undo/Redo Stack    |

Key Modules:
**Keyboard Module:**
- Backspace handling
- Delete handling
- Enter handling
- Space handling
- Tab handling
- Key event management

**Node Module:**
- Block management
- Tree traversal
- Node categorization
- Whitespace handling

**Range Module:**
- Selection boundaries
- Content management
- Insert/Delete operations
- Block operations

##### Interaction Flows

Key flows:
- Input handling path
- DOM event propagation
- Sanitization process
- Content modification pipeline

##### Integration Points

Highlight:
- DOM interface
- Custom UI integration points
- Sanitization hooks (DOMPurify integration)
- Event listener attachment points

##### Key Relationships

**UI Integration → Editor Instance → DOM**
- ↓

- ↓            ↓            ↓
- Keyboard      Node         Range
- Handlers    Management    Management
- ↓            ↓            ↓

- ↓
- DOM Manipulation

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph UI["UI Integration Layer"]
        UI_INT[User Interface Integration]
    end

    subgraph Core["Core Editor Layer"]
        EDITOR[Squire Editor]:::core
        SQUIRE[Editor Instance]:::core
    end

    subgraph Modules["Module Layer"]
        direction TB
        subgraph KBD["Keyboard Module"]
            direction TB
            KH[Key Handlers]:::kbd
            BH[Backspace Handler]:::kbd
            DH[Delete Handler]:::kbd
            EH[Enter Handler]:::kbd
            SH[Space Handler]:::kbd
            TH[Tab Handler]:::kbd
        end

        subgraph NODE["Node Management"]
            direction TB
            NM[Node Manager]:::node
            BM[Block Manager]:::node
            CAT[Node Categorization]:::node
            TREE[Tree Iterator]:::node
            WS[Whitespace Handler]:::node
            MS[Merge Split]:::node
        end

        subgraph RANGE["Range Management"]
            direction TB
            BOUND[Boundaries]:::range
            CONT[Contents]:::range
            INSDEL[Insert/Delete]:::range
            BLOCK[Block Operations]:::range
        end

        CLIP[Clipboard Manager]:::util
        CLEAN[Sanitization]:::security
        CONST[Constants]:::util
        LEGACY[Legacy Support]:::util
    end

    subgraph DOM["DOM Integration Layer"]
        DOM_INT[DOM Interface]
        EVENT[Event System]
        HTML[HTML Management]
    end

    %% Relationships
    UI_INT --> EDITOR
    EDITOR --> SQUIRE
    SQUIRE --> DOM_INT
    SQUIRE --> EVENT
    SQUIRE --> HTML

    SQUIRE --> KBD
    SQUIRE --> NODE
    SQUIRE --> RANGE
    SQUIRE --> CLIP
    SQUIRE --> CLEAN

    KBD --> DOM_INT
    NODE --> DOM_INT
    RANGE --> DOM_INT
    CLEAN --> HTML

    %% Click Events
    click EDITOR "https://github.com/fastmail/Squire/blob/master/source/Editor.ts"
    click SQUIRE "https://github.com/fastmail/Squire/blob/master/source/Squire.ts"
    click KH "https://github.com/fastmail/Squire/blob/master/source/keyboard/KeyHandlers.ts"
    click BH "https://github.com/fastmail/Squire/blob/master/source/keyboard/Backspace.ts"
    click DH "https://github.com/fastmail/Squire/blob/master/source/keyboard/Delete.ts"
    click EH "https://github.com/fastmail/Squire/blob/master/source/keyboard/Enter.ts"
    click SH "https://github.com/fastmail/Squire/blob/master/source/keyboard/Space.ts"
    click TH "https://github.com/fastmail/Squire/blob/master/source/keyboard/Tab.ts"
    click NM "https://github.com/fastmail/Squire/blob/master/source/node/Node.ts"
    click BM "https://github.com/fastmail/Squire/blob/master/source/node/Block.ts"
    click CAT "https://github.com/fastmail/Squire/blob/master/source/node/Category.ts"
    click TREE "https://github.com/fastmail/Squire/blob/master/source/node/TreeIterator.ts"
    click WS "https://github.com/fastmail/Squire/blob/master/source/node/Whitespace.ts"
    click MS "https://github.com/fastmail/Squire/blob/master/source/node/MergeSplit.ts"
    click BOUND "https://github.com/fastmail/Squire/blob/master/source/range/Boundaries.ts"
    click CONT "https://github.com/fastmail/Squire/blob/master/source/range/Contents.ts"
    click INSDEL "https://github.com/fastmail/Squire/blob/master/source/range/InsertDelete.ts"
    click BLOCK "https://github.com/fastmail/Squire/blob/master/source/range/Block.ts"
    click CLIP "https://github.com/fastmail/Squire/blob/master/source/Clipboard.ts"
    click CLEAN "https://github.com/fastmail/Squire/blob/master/source/Clean.ts"
    click CONST "https://github.com/fastmail/Squire/blob/master/source/Constants.ts"
    click LEGACY "https://github.com/fastmail/Squire/blob/master/source/Legacy.ts"

    %% Styling
    classDef core fill:#2374ab
    classDef kbd fill:#57a773
    classDef node fill:#4ba3c3
    classDef range fill:#175676
    classDef util fill:#ba9790
    classDef security fill:#d64933

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Keyboard Handlers]:::kbd
        L3[Node Management]:::node
        L4[Range Management]:::range
        L5[Utility Modules]:::util
        L6[Security Components]:::security
    end
```
