# jimbrig/dotfiles-espanso architecture

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

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

## Overview

##### Main Components
- Configurations: The main configuration settings are stored in the “config” folder. This includes the default settings (default.yml) that determine Espanso’s runtime behavior (e.g., toggle_key, search_shortcut, etc.).
- Match Files: The “match” folder stores all the trigger/replacement definitions in YAML files. Each of these files (like about.yml, address.yml, etc.) defines different types (or categories) of text expansions.
- Packages: Within the “match” folder is a “packages” subdirectory. This area holds packages (such as docker-compose, get-ip, lorem, markdown-shortcuts, rand-tools, and wttr) which extend functionality via additional match definitions or custom scripts.
- Encryption & Security: The inclusion of git-crypt files (.git-crypt directory) indicates that some parts (like passwords.yml and secrets.yml within “match”) are secured. This implies an additional layer of security/permission management over sensitive data.
- Metadata & Auxiliary Files: Directories like .github (workflows, CI/CD pipelines), schema (for configuration and Espanso’s match schema), and typical dotfiles (.gitignore, .gitattributes, etc.) provide supplementary configuration to manage the repository lifecycle.

##### Relationships and Data Flow
- User Input → Espanso Runtime: Drawing the conversion of typing “trigger keywords” which are picked up by Espanso’s runtime process.
- Match Processing: Then, show a flow where the runtime consults the “match” files to check for any keyword matches and what content to expand.
- Dependency on Packages: Include a branch for “Packages” wherein specialized expansions are modularly added, affecting how triggers are interpreted.
- Security Layer: Illustrate that some match files (like passwords and secrets) are encrypted (via git-crypt) to highlight security considerations.

##### Architectural Patterns and Design Principles
- File-based Configuration: Emphasize that Espanso uses a direct file-based configuration approach rather than a database or centralized server, which simplifies the architecture.
- Modular Extensibility: The separation between base match files and packages demonstrates modular extensibility. Each package is self-contained and can be updated independently.
- Separation of Concerns: There is clear demarcation between user-specific configurations (config) and the actual expansion definitions (match). This decoupling simplifies management and integration with the Espanso core.
- Security by Design: The use of git-crypt indicates a design where sensitive data is kept secure, even within the version-controlled configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U("User Input"):::user
    E("Espanso Engine (Rust)"):::engine
    C("Config (default.yml)"):::config
    M("Match Files"):::match
    P("Packages"):::packages
    S("Git-Crypt (Encryption)"):::security
    G(".github (CI/CD)"):::metadata
    SC("Schema (Validation)"):::metadata

    U -->|"inputs"| E
    E -->|"reads"| C
    E -->|"consults"| M
    M -->|"includes"| P
    M -->|"securedBy"| S
    E -->|"integrates"| G
    E -->|"validatesWith"| SC

    click C "https://github.com/jimbrig/dotfiles-espanso/blob/main/config/default.yml"
    click M "https://github.com/jimbrig/dotfiles-espanso/tree/main/match/"
    click P "https://github.com/jimbrig/dotfiles-espanso/tree/main/match/packages/"
    click S "https://github.com/jimbrig/dotfiles-espanso/tree/main/.git-crypt/"
    click G "https://github.com/jimbrig/dotfiles-espanso/tree/main/.github/"
    click SC "https://github.com/jimbrig/dotfiles-espanso/tree/main/schema/"

    classDef user fill:#fce4ec,stroke:#ad1457,stroke-width:2px;
    classDef engine fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef config fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef match fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;
    classDef packages fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef security fill:#fff3e0,stroke:#ef6c00,stroke-width:2px;
    classDef metadata fill:#f1f8e9,stroke:#33691e,stroke-width:2px;
```
