# embroidery-space/embroiderly architecture

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

- Interactive diagram: https://gitdiagram.com/embroidery-space/embroiderly
- Repository: https://github.com/embroidery-space/embroiderly

## Overview

##### Project Type and Purpose
- Full-stack desktop application (not a web service) built with Tauri.
- Purpose: allow users to create, edit, view, and export cross-stitch patterns.
- Key characteristics: local file I/O of pattern files (OXs/XSD), in-app pattern rendering, interactive UI.

##### High-Level Architectural Components
a. Frontend Layer
– Vue.js SPA (src/)
– Components (CanvasPanel, PalettePanel, dialogs, toolbar, etc.)
– State management via Pinia (stores/)
– API wrappers (src/api/*.ts) that call into Tauri commands
– Assets & themes (src/assets/)
– Pixi plugin for canvas rendering (src/plugins/pixi/)
b. Tauri Runtime & IPC
– Tauri acts as a bridge between WebView UI and the Rust binary
– IPC channels for invoking “commands” defined in Rust
c. Backend Layer (Rust in src-tauri/)
– Command interface (src-tauri/src/commands/*.rs) – entry points for IPC from frontend
– Core domain logic (src-tauri/src/core/)
- Actions (display, grid, palette, stitches, fabric, history)
- Parser submodules for .oxs and .xsd formats
- Pattern model, project serialization, printing
– Utilities (logger, state, path helpers)
d. Persistence & File System
– Local filesystem reads/writes for patterns, palettes, fabrics
– Config/state persisted via JSON or binary (Borsh) formats

##### Relationships and Data Flow
1. User interacts with Vue UI → triggers a UI event.
2. UI calls an API wrapper in src/api → invokes a Tauri command over IPC.
3. Tauri routes the call to the corresponding Rust command handler.
4. Command handler invokes core domain logic (parsers, actions).
5. Core logic may:
- Read or parse pattern/fabric files from disk
- Modify in-memory pattern model or history
- Serialize state changes (history, project save) back to disk
6. Rust returns a result (data structure or status) via IPC to the frontend.
7. Frontend receives data → commits to Pinia store → UI updates (canvas repaint via Pixi).

##### Architectural Patterns and Principles
- Layered separation – UI layer, application layer (API wrappers), domain/core layer, persistence layer.
- Command pattern – each operation exposed via a distinct Rust command module.
- MVVM‐style frontend – Vue components + Pinia stores.
- Plugin/extensible design – “extensions” and “capabilities” directories in src-tauri for third-party add-ons.
- Strict type/schema definitions – schemas/pattern and core/parser modules, tests for coverage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UI_Canvas["CanvasPanel.vue"]:::frontend
        UI_Palette["PalettePanel.vue"]:::frontend
        UI_Prefs["AppPreferences.vue"]:::frontend
        UI_Toolbar["CanvasToolbar.vue"]:::frontend
        Store["Pinia Store (src/stores/)"]:::frontend
        API_Display["display.ts"]:::frontend
        API_Pattern["pattern.ts"]:::frontend
        Assets_Icons["src/assets/icons/"]:::frontend
        Assets_Theme["src/assets/theme/"]:::frontend
        Pixi_Canvas["pattern-canvas.ts"]:::frontend
        Pixi_Display["display-objects.ts"]:::frontend
    end

    %% Tauri IPC Layer
    subgraph "Tauri Runtime & IPC" 
        direction TB
        TauriConfig["tauri.conf.json"]:::tauri
    end

    %% Rust Command Interface
    subgraph "Rust Commands (IPC Handlers)"
        direction TB
        Cmd_Display["display.rs"]:::backend
        Cmd_Pattern["pattern.rs"]:::backend
    end

    %% Core Domain Logic
    subgraph "Core Domain Logic"
        direction TB
        subgraph Actions
            direction TB
            Action_Display["display.rs"]:::core
            Action_Grid["grid.rs"]:::core
        end
        subgraph Parsers
            direction TB
            Parser_OXS["oxs.rs"]:::core
            Parser_XSD["read.rs"]:::core
        end
        subgraph PatternModel
            direction TB
            Model_Pattern["pattern.rs"]:::core
            Model_Print["print.rs"]:::core
        end
        Utils["path.rs"]:::core
        Logger["logger.rs"]:::core
        AppState["state.rs"]:::core
    end

    %% File System & Resources
    subgraph "Local File System & Resources"
        direction TB
        FS_Resources["src-tauri/resources/"]:::fs
        FS_Palettes["palettes/"]:::fs
        FS_Patterns["patterns/"]:::fs
        FS_Extensions["src-tauri/extensions/"]:::backend
        FS_Capabilities["src-tauri/capabilities/"]:::backend
        FS_TestData["src-tauri/testdata/"]:::fs
    end

    %% Data Flow
    UI_Canvas -->|"reads/writes state"| Store
    UI_Palette -->|commits| Store
    UI_Prefs -->|commits| Store
    UI_Toolbar -->|triggers API| API_Display
    Store -->|calls| API_Pattern
    API_Display -->|"invoke IPC"| TauriConfig
    API_Pattern -->|"invoke IPC"| TauriConfig
    TauriConfig -->|routes to| Cmd_Display
    TauriConfig -->|routes to| Cmd_Pattern
    Cmd_Display -->|calls| Action_Display
    Cmd_Pattern -->|calls| Parser_OXS
    Cmd_Pattern -->|calls| Parser_XSD
    Action_Display -->|uses| Model_Pattern
    Action_Grid -->|uses| Model_Pattern
    Parser_OXS -->|loads/saves| FS_Resources
    Parser_XSD -->|loads/saves| FS_Resources
    Action_Display -->|logs via| Logger
    Cmd_Display -->|updates| AppState
    AppState -->|persists| FS_TestData
    Model_Print -->|writes| FS_Patterns
    FS_Extensions -->|loaded by| Cmd_Display
    FS_Capabilities -->|loaded by| Cmd_Display

    %% Return flow to UI
    Cmd_Display -->|returns data| TauriConfig
    TauriConfig -->|response| API_Display
    API_Display -->|resolves promise| Store
    Store -->|updates| UI_Canvas

    %% Click Events
    click UI_Canvas "https://github.com/embroidery-space/embroiderly/blob/main/src/components/CanvasPanel.vue"
    click UI_Palette "https://github.com/embroidery-space/embroiderly/blob/main/src/components/PalettePanel.vue"
    click UI_Prefs "https://github.com/embroidery-space/embroiderly/blob/main/src/components/dialogs/AppPreferences.vue"
    click UI_Toolbar "https://github.com/embroidery-space/embroiderly/blob/main/src/components/toolbar/CanvasToolbar.vue"
    click Store "https://github.com/embroidery-space/embroiderly/tree/main/src/stores/"
    click API_Display "https://github.com/embroidery-space/embroiderly/blob/main/src/api/display.ts"
    click API_Pattern "https://github.com/embroidery-space/embroiderly/blob/main/src/api/pattern.ts"
    click Assets_Icons "https://github.com/embroidery-space/embroiderly/tree/main/src/assets/icons/"
    click Assets_Theme "https://github.com/embroidery-space/embroiderly/tree/main/src/assets/theme/"
    click Pixi_Canvas "https://github.com/embroidery-space/embroiderly/blob/main/src/plugins/pixi/pattern-canvas.ts"
    click Pixi_Display "https://github.com/embroidery-space/embroiderly/blob/main/src/plugins/pixi/display-objects.ts"
    click TauriConfig "https://github.com/embroidery-space/embroiderly/blob/main/src-tauri/tauri.conf.json"
    click Cmd_Display "https://github.com/embroidery-space/embroiderly/blob/main/src-tauri/src/commands/display.rs"
    click Cmd_Pattern "https://github.com/embroidery-space/embroiderly/blob/main/src-tauri/src/commands/pattern.rs"
    click Action_Display "https://github.com/embroidery-space/embroiderly/blob/main/src-tauri/src/core/actions/display.rs"
    click Action_Grid "https://github.com/embroidery-space/embroiderly/blob/main/src-tauri/src/core/actions/grid.rs"
    click Parser_OXS "https://github.com/embroidery-space/embroiderly/blob/main/src-tauri/src/core/parser/oxs/oxs.rs"
    click Parser_XSD "https://github.com/embroidery-space/embroiderly/blob/main/src-tauri/src/core/parser/xsd/read.rs"
    click Model_Pattern "https://github.com/embroidery-space/embroiderly/blob/main/src-tauri/src/core/pattern/pattern.rs"
    click Model_Print "https://github.com/embroidery-space/embroiderly/blob/main/src-tauri/src/core/pattern/print.rs"
    click Utils "https://github.com/embroidery-space/embroiderly/blob/main/src-tauri/src/utils/path.rs"
    click Logger "https://github.com/embroidery-space/embroiderly/blob/main/src-tauri/src/logger.rs"
    click AppState "https://github.com/embroidery-space/embroiderly/blob/main/src-tauri/src/state.rs"
    click FS_Resources "https://github.com/embroidery-space/embroiderly/tree/main/src-tauri/resources/"
    click FS_Palettes "https://github.com/embroidery-space/embroiderly/tree/main/src-tauri/resources/palettes/"
    click FS_Patterns "https://github.com/embroidery-space/embroiderly/tree/main/src-tauri/resources/patterns/"
    click FS_Extensions "https://github.com/embroidery-space/embroiderly/tree/main/src-tauri/extensions/"
    click FS_Capabilities "https://github.com/embroidery-space/embroiderly/tree/main/src-tauri/capabilities/"
    click FS_TestData "https://github.com/embroidery-space/embroiderly/tree/main/src-tauri/testdata/"

    %% Styles
    classDef frontend fill:#D6E4FF,stroke:#4C85FF;
    classDef tauri fill:#DFFFE0,stroke:#4CAF50;
    classDef backend fill:#FFF4D6,stroke:#FFB400;
    classDef core fill:#FFE8E8,stroke:#FF5252;
    classDef fs fill:#F2F2F2,stroke:#AAAAAA;
```
