# lukeledesma/alchemy architecture

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

- Interactive diagram: https://gitdiagram.com/lukeledesma/alchemy
- Repository: https://github.com/lukeledesma/alchemy

## Overview

Alchemy is a macOS desktop editor for UTICOR Modbus router XML documents. Operators open or navigate to a document, inspect and edit table rows and connection settings, receive inline validation feedback, then save through a deterministic XML pipeline that repairs and regenerates preload data. The storage panel also supports folder navigation and file management. The graph reflects README-documented save and validation capabilities; their implementation details are not present in the sampled excerpts.

Main entry points: [`src/Alchemy/AlchemyWindow.axaml.cs`](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyWindow.axaml.cs) (Editor window), [`src/Alchemy/AlchemyWindow.Panel.cs`](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyWindow.Panel.cs) (Storage panel), [`src/Alchemy/Program.cs`](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/Program.cs) (Application entry), [`src/Alchemy/AlchemyWindow.DataFlow.cs`](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyWindow.DataFlow.cs) (Parse and diagnostics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop editor"]
  node_program["Application entry<br/>[Program.cs]"]
  node_app["Avalonia app"]
  node_window["Editor window"]
  node_windowui["Editor layout"]
  node_settings["App settings<br/>[AlchemySettings.cs]"]
  node_launchcontext["Launch context"]
end

subgraph group_document["Document workflow"]
  node_dataflow["Parse and diagnostics"]
  node_catalog["UTICOR data catalog"]
  node_dictionary["UTICOR dictionary"]
end

subgraph group_storage["Storage panel"]
  node_panel["Storage panel"]
  node_pathrules["Path safety rules"]
end

subgraph group_platform["Platform integration"]
  node_kitfiles["Finder operations"]
  node_trash["Trash integration<br/>[MacFileTrash.cs]"]
  node_nativeui["macOS window UI<br/>[MacTitleBar.cs]"]
  node_textkit["Text editing behaviors"]
end

node_operator(("Operator"))
node_xml["Router XML"]
node_filesystem[("Local filesystem")]

node_operator -->|"launches"| node_program
node_program -->|"starts"| node_app
node_operator -->|"edits document"| node_window
node_window -->|"renders"| node_windowui
node_window -->|"parses and validates"| node_dataflow
node_dataflow -->|"looks up labels"| node_catalog
node_catalog -->|"loads"| node_dictionary
node_window -->|"opens and saves"| node_xml
node_window -->|"manages files"| node_panel
node_panel -->|"lists and changes"| node_filesystem
node_panel -->|"checks moves"| node_pathrules
node_panel -->|"opens or reveals"| node_kitfiles
node_panel -->|"trashes entries"| node_trash
node_window -->|"aligns title bar"| node_nativeui
node_window -->|"creates editors"| node_textkit
node_window -->|"uses settings"| node_settings
node_program -.->|"launch context"| node_launchcontext

click node_program "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/Program.cs"
click node_app "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyApp.axaml.cs"
click node_window "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyWindow.axaml.cs"
click node_windowui "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyWindow.axaml"
click node_dataflow "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyWindow.DataFlow.cs"
click node_catalog "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyDataCatalog.cs"
click node_dictionary "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/Data/Uticor%20Dictionary.txt"
click node_settings "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemySettings.cs"
click node_panel "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyWindow.Panel.cs"
click node_pathrules "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy.Core/StoragePathRules.cs"
click node_launchcontext "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy.Core/ToolLaunchContext.cs"
click node_kitfiles "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy.Kit/FileManagerReveal.cs"
click node_trash "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy.Kit/MacFileTrash.cs"
click node_nativeui "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy.Kit/MacTitleBar.cs"
click node_textkit "https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy.Kit/TextBoxBehaviors.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_program,node_app,node_window,node_windowui,node_settings,node_launchcontext toneBlue
class node_dataflow,node_catalog,node_dictionary,node_filesystem toneAmber
class node_panel,node_pathrules,node_xml toneMint
class node_kitfiles,node_trash,node_nativeui,node_textkit toneRose
class node_operator toneIndigo
```

## Components

### Desktop editor

- [Application entry](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/Program.cs): `src/Alchemy/Program.cs`
- [Avalonia app](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyApp.axaml.cs): `src/Alchemy/AlchemyApp.axaml.cs`
- [Editor window](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyWindow.axaml.cs): `src/Alchemy/AlchemyWindow.axaml.cs`
- [Editor layout](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyWindow.axaml): `src/Alchemy/AlchemyWindow.axaml`
- [App settings](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemySettings.cs): `src/Alchemy/AlchemySettings.cs`
- [Launch context](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy.Core/ToolLaunchContext.cs): `src/Alchemy.Core/ToolLaunchContext.cs`

### Document workflow

- [Parse and diagnostics](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyWindow.DataFlow.cs): `src/Alchemy/AlchemyWindow.DataFlow.cs`
- [UTICOR data catalog](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyDataCatalog.cs): `src/Alchemy/AlchemyDataCatalog.cs`
- [UTICOR dictionary](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/Data/Uticor%20Dictionary.txt): `src/Alchemy/Data/Uticor Dictionary.txt`

### Storage panel

- [Storage panel](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy/AlchemyWindow.Panel.cs): `src/Alchemy/AlchemyWindow.Panel.cs`
- [Path safety rules](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy.Core/StoragePathRules.cs): `src/Alchemy.Core/StoragePathRules.cs`

### Platform integration

- [Finder operations](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy.Kit/FileManagerReveal.cs): `src/Alchemy.Kit/FileManagerReveal.cs`
- [Trash integration](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy.Kit/MacFileTrash.cs): `src/Alchemy.Kit/MacFileTrash.cs`
- [macOS window UI](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy.Kit/MacTitleBar.cs): `src/Alchemy.Kit/MacTitleBar.cs`
- [Text editing behaviors](https://github.com/lukeledesma/alchemy/blob/main/src/Alchemy.Kit/TextBoxBehaviors.cs): `src/Alchemy.Kit/TextBoxBehaviors.cs`

### Other components

- **Operator**
- **Router XML**
- **Local filesystem**

## Connections

- Operator → Application entry: launches
- Application entry → Avalonia app: starts
- Operator → Editor window: edits document
- Editor window → Editor layout: renders
- Editor window → Parse and diagnostics: parses and validates
- Parse and diagnostics → UTICOR data catalog: looks up labels
- UTICOR data catalog → UTICOR dictionary: loads
- Editor window → Router XML: opens and saves
- Editor window → Storage panel: manages files
- Storage panel → Local filesystem: lists and changes
- Storage panel → Path safety rules: checks moves
- Storage panel → Finder operations: opens or reveals
- Storage panel → Trash integration: trashes entries
- Editor window → macOS window UI: aligns title bar
- Editor window → Text editing behaviors: creates editors
- Editor window → App settings: uses settings
- Application entry → Launch context: launch context