# espanso/espanso architecture

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

- Interactive diagram: https://gitdiagram.com/espanso/espanso
- Repository: https://github.com/espanso/espanso

## Overview

##### High-Level Architecture Components

The system should be divided into these main components:

a) Core Components:
- Engine (espanso-engine): Central processing unit
- Config (espanso-config): Configuration management
- Match (espanso-match): Text matching system
- Render (espanso-render): Text expansion rendering
- Package (espanso-package): Package management system

b) Platform-specific Components:
- Detect (espanso-detect): Input detection layer
- Inject (espanso-inject): Text injection system
- Clipboard (espanso-clipboard): Clipboard management
- Info (espanso-info): System information gathering
- UI (espanso-ui): User interface components

##### Component Relationships

**User Input -> Detect -> Engine -> Inject -> System Output**
- ↑
- Config
- ↑
- Match
- ↑
- Render

##### Detailed Component Breakdown

For each major component, show internal structure:

Engine:
- Dispatch System
- Event Processing
- Middleware Chain
- Match Processing

Match System:
- Regex Matcher
- Rolling Matcher
- Match Selection
- Pattern Processing

Config System:
- YAML Parser
- Config Store
- Match Groups
- Path Resolution

##### Cross-Platform Architecture

Platform-specific implementations:
- Platform Layer
- ↓
**[Windows] [macOS] [Linux/X11] [Wayland]**
- ↓
- Core Components

##### Data Flow

Main data flow:

##### Key Integration Points

Integration with:
- System clipboard
- File system
- GUI framework (wxWidgets)
- IPC mechanisms
- Package management system

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style Definitions
    classDef core fill:#a8d1f0,stroke:#333
    classDef platform fill:#90EE90,stroke:#333
    classDef ui fill:#FFB347,stroke:#333
    classDef ipc fill:#DDA0DD,stroke:#333
    classDef security fill:#FFB6C1,stroke:#333

    %% Platform Layer
    subgraph PlatformLayer["Platform Implementations"]
        Windows["Windows"]:::platform
        MacOS["macOS"]:::platform
        Linux["Linux/X11"]:::platform
        Wayland["Wayland"]:::platform
    end

    %% Core Components
    subgraph CoreComponents["Core Components"]
        Engine["Engine"]:::core
        Config["Config"]:::core
        Match["Match"]:::core
        Render["Render"]:::core
        Package["Package"]:::core

        %% Engine Subcomponents
        subgraph EngineComponents["Engine Components"]
            Dispatch["Dispatch System"]:::core
            EventProc["Event Processing"]:::core
            Middleware["Middleware Chain"]:::core
            MatchProc["Match Processing"]:::core
        end

        %% Match Subcomponents
        subgraph MatchComponents["Match Components"]
            RegexMatch["Regex Matcher"]:::core
            RollingMatch["Rolling Matcher"]:::core
            PatternProc["Pattern Processing"]:::core
        end

        %% Config Subcomponents
        subgraph ConfigComponents["Config Components"]
            YAMLParser["YAML Parser"]:::core
            ConfigStore["Config Store"]:::core
            MatchGroups["Match Groups"]:::core
        end
    end

    %% Platform-specific Components
    subgraph PlatformComponents["Platform-specific Components"]
        Detect["Detect"]:::platform
        Inject["Inject"]:::platform
        Clipboard["Clipboard"]:::platform
        Info["Info"]:::platform
        UI["UI"]:::platform
    end

    %% Main Flow
    UserInput[/"User Input"/] --> Detect
    Detect --> Engine
    Engine --> Inject
    Inject --> SystemOutput[/"System Output"/]

    %% Component Relationships
    Engine --> Config
    Config --> Match
    Match --> Render
    Package --> Config

    %% Click Events
    click Engine "https://github.com/espanso/espanso/tree/dev/espanso-engine/"
    click Dispatch "https://github.com/espanso/espanso/tree/dev/espanso-engine/src/dispatch/"
    click EventProc "https://github.com/espanso/espanso/tree/dev/espanso-engine/src/event/"
    click Middleware "https://github.com/espanso/espanso/tree/dev/espanso-engine/src/process/middleware/"
    click Config "https://github.com/espanso/espanso/tree/dev/espanso-config/"
    click YAMLParser "https://github.com/espanso/espanso/blob/dev/espanso-config/src/config/parse/yaml.rs"
    click MatchGroups "https://github.com/espanso/espanso/tree/dev/espanso-config/src/matches/group/"
    click ConfigStore "https://github.com/espanso/espanso/blob/dev/espanso-config/src/config/store.rs"
    click Match "https://github.com/espanso/espanso/tree/dev/espanso-match/"
    click RegexMatch "https://github.com/espanso/espanso/tree/dev/espanso-match/src/regex/"
    click RollingMatch "https://github.com/espanso/espanso/tree/dev/espanso-match/src/rolling/"
    click PatternProc "https://github.com/espanso/espanso/blob/dev/espanso-match/src/rolling/matcher.rs"
    click Render "https://github.com/espanso/espanso/tree/dev/espanso-render/"
    click Package "https://github.com/espanso/espanso/tree/dev/espanso-package/"
    click Detect "https://github.com/espanso/espanso/tree/dev/espanso-detect/"
    click Inject "https://github.com/espanso/espanso/tree/dev/espanso-inject/"
    click Clipboard "https://github.com/espanso/espanso/tree/dev/espanso-clipboard/"
    click Info "https://github.com/espanso/espanso/tree/dev/espanso-info/"
    click UI "https://github.com/espanso/espanso/tree/dev/espanso-ui/"

    %% Legend
    subgraph Legend
        CoreComp["Core Component"]:::core
        PlatformComp["Platform Component"]:::platform
        UIComp["UI Component"]:::ui
        IPCComp["IPC/Communication"]:::ipc
    end
```
