# herra-atlas/project-m architecture

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

- Interactive diagram: https://gitdiagram.com/herra-atlas/project-m
- Repository: https://github.com/herra-atlas/project-m

## Overview

Project M is a visual Windows macro-authoring and automation app. Users create or import a node graph, save it as a per-macro folder, then run it; the Rust engine dispatches graph nodes that drive keyboard, mouse, pixel, script, and IPC actions. A parallel AI workflow chats with an OpenAI-compatible model and turns proposed changes into confirmation-gated macro actions. The README documents storage, force-stop, and auto-update capabilities; some backend command wiring and UI details were not fully excerpted, so uncertain links are omitted or marked unverified.

Main entry points: [`src/App.tsx`](https://github.com/herra-atlas/project-m/blob/main/src/App.tsx) (App shell), [`src-tauri/src/main.rs`](https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/main.rs) (Tauri commands), [`src/components/CreateWithAiModal.tsx`](https://github.com/herra-atlas/project-m/blob/main/src/components/CreateWithAiModal.tsx) (AI chat and approvals), [`src/components/editor/EditorPage.tsx`](https://github.com/herra-atlas/project-m/blob/main/src/components/editor/EditorPage.tsx) (Graph editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Macro authoring"]
  node_app["App shell<br/>[App.tsx]"]
  node_editor["Graph editor<br/>[EditorPage.tsx]"]
  node_canvas["Node canvas<br/>[EditorCanvas.tsx]"]
  node_nodeview["Node rendering<br/>[Node.tsx]"]
  node_palette["Node palette<br/>[NodePalette.tsx]"]
end

subgraph group_ai["AI assistant"]
  node_aiui["AI chat and approvals"]
  node_aiprotocol["Fence parser<br/>[protocol.ts]"]
end

subgraph group_runtime["Macro runtime"]
  node_macrodata["Macro graph data<br/>[macro_data.rs]"]
  node_engine["Graph engine<br/>[engine.rs]"]
  node_dispatch["Node dispatcher<br/>[mod.rs]"]
  node_automation["Input and vision<br/>[input.rs]"]
  node_scriptnodes["Script and IPC nodes"]
end

subgraph group_services["Storage and integrations"]
  node_tauri["Tauri commands<br/>[main.rs]"]
  node_macrofs[("Macro folders<br/>[macros_fs.rs]")]
  node_ahkipc["AHK IPC<br/>[ahk_ipc.rs]"]
  node_logs["Runtime logs<br/>[LogsPanel.tsx]"]
  node_updater["Update client<br/>[useUpdater.ts]"]
end

node_user(("User"))
node_model["Chat model"]
node_releases["GitHub Releases"]

node_user -->|"uses"| node_app
node_app -->|"mounts"| node_editor
node_editor -->|"renders"| node_canvas
node_canvas -->|"renders"| node_nodeview
node_editor -->|"renders"| node_palette
node_user -->|"describes macro"| node_aiui
node_aiui -->|"streams chat"| node_model
node_aiui -->|"parses fences"| node_aiprotocol
node_aiui -->|"invokes commands"| node_tauri
node_model -->|"returns draft"| node_aiui
node_editor -.->|"runs macro"| node_tauri
node_app -->|"invokes commands"| node_tauri
node_tauri -->|"starts and stops"| node_engine
node_tauri -.->|"manages macro files"| node_macrofs
node_engine -->|"loads graph"| node_macrodata
node_engine -->|"dispatches nodes"| node_dispatch
node_dispatch -->|"performs input and scans"| node_automation
node_dispatch -->|"routes node types"| node_scriptnodes
node_scriptnodes -.->|"sends IPC"| node_ahkipc
node_user -->|"requests force stop"| node_app
node_app -->|"requests stop"| node_tauri
node_app -->|"opens runtime logs"| node_logs
node_app -->|"checks updates"| node_updater
node_updater -->|"checks releases"| node_releases

click node_app "https://github.com/herra-atlas/project-m/blob/main/src/App.tsx"
click node_editor "https://github.com/herra-atlas/project-m/blob/main/src/components/editor/EditorPage.tsx"
click node_canvas "https://github.com/herra-atlas/project-m/blob/main/src/components/editor/EditorCanvas.tsx"
click node_nodeview "https://github.com/herra-atlas/project-m/blob/main/src/components/editor/Node.tsx"
click node_palette "https://github.com/herra-atlas/project-m/blob/main/src/components/editor/NodePalette.tsx"
click node_aiui "https://github.com/herra-atlas/project-m/blob/main/src/components/CreateWithAiModal.tsx"
click node_aiprotocol "https://github.com/herra-atlas/project-m/blob/main/src/components/ai/protocol.ts"
click node_tauri "https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/main.rs"
click node_macrofs "https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/macros_fs.rs"
click node_macrodata "https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/macro_data.rs"
click node_engine "https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/engine.rs"
click node_dispatch "https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/nodes/mod.rs"
click node_automation "https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/input.rs"
click node_scriptnodes "https://github.com/herra-atlas/project-m/tree/main/src-tauri/src/nodes"
click node_ahkipc "https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/ahk_ipc.rs"
click node_logs "https://github.com/herra-atlas/project-m/blob/main/src/components/LogsPanel.tsx"
click node_updater "https://github.com/herra-atlas/project-m/blob/main/src/components/useUpdater.ts"

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_app,node_editor,node_canvas,node_nodeview,node_palette,node_user toneBlue
class node_aiui,node_aiprotocol toneAmber
class node_macrodata,node_engine,node_dispatch,node_automation,node_scriptnodes toneMint
class node_tauri,node_macrofs,node_ahkipc,node_logs,node_updater toneRose
class node_model,node_releases toneIndigo
```

## Components

### Macro authoring

- [App shell](https://github.com/herra-atlas/project-m/blob/main/src/App.tsx): `src/App.tsx`
- [Graph editor](https://github.com/herra-atlas/project-m/blob/main/src/components/editor/EditorPage.tsx): `src/components/editor/EditorPage.tsx`
- [Node canvas](https://github.com/herra-atlas/project-m/blob/main/src/components/editor/EditorCanvas.tsx): `src/components/editor/EditorCanvas.tsx`
- [Node rendering](https://github.com/herra-atlas/project-m/blob/main/src/components/editor/Node.tsx): `src/components/editor/Node.tsx`
- [Node palette](https://github.com/herra-atlas/project-m/blob/main/src/components/editor/NodePalette.tsx): `src/components/editor/NodePalette.tsx`

### AI assistant

- [AI chat and approvals](https://github.com/herra-atlas/project-m/blob/main/src/components/CreateWithAiModal.tsx): `src/components/CreateWithAiModal.tsx`
- [Fence parser](https://github.com/herra-atlas/project-m/blob/main/src/components/ai/protocol.ts): `src/components/ai/protocol.ts`

### Macro runtime

- [Macro graph data](https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/macro_data.rs): `src-tauri/src/macro_data.rs`
- [Graph engine](https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/engine.rs): `src-tauri/src/engine.rs`
- [Node dispatcher](https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/nodes/mod.rs): `src-tauri/src/nodes/mod.rs`
- [Input and vision](https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/input.rs): `src-tauri/src/input.rs`
- [Script and IPC nodes](https://github.com/herra-atlas/project-m/tree/main/src-tauri/src/nodes): `src-tauri/src/nodes`

### Storage and integrations

- [Tauri commands](https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/main.rs): `src-tauri/src/main.rs`
- [Macro folders](https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/macros_fs.rs): `src-tauri/src/macros_fs.rs`
- [AHK IPC](https://github.com/herra-atlas/project-m/blob/main/src-tauri/src/ahk_ipc.rs): `src-tauri/src/ahk_ipc.rs`
- [Runtime logs](https://github.com/herra-atlas/project-m/blob/main/src/components/LogsPanel.tsx): `src/components/LogsPanel.tsx`
- [Update client](https://github.com/herra-atlas/project-m/blob/main/src/components/useUpdater.ts): `src/components/useUpdater.ts`

### Other components

- **User**
- **Chat model**
- **GitHub Releases**

## Connections

- User → App shell: uses (evidence: `README.md`)
- App shell → Graph editor: mounts (evidence: `src/App.tsx`)
- Graph editor → Node canvas: renders (evidence: `src/components/editor/EditorPage.tsx`)
- Node canvas → Node rendering: renders (evidence: `src/components/editor/EditorCanvas.tsx`)
- Graph editor → Node palette: renders (evidence: `src/components/editor/EditorPage.tsx`)
- User → AI chat and approvals: describes macro (evidence: `README.md`)
- AI chat and approvals → Chat model: streams chat (evidence: `src/components/CreateWithAiModal.tsx`)
- AI chat and approvals → Fence parser: parses fences (evidence: `src/components/CreateWithAiModal.tsx`)
- AI chat and approvals → Tauri commands: invokes commands (evidence: `src/components/CreateWithAiModal.tsx`)
- Chat model → AI chat and approvals: returns draft (evidence: `README.md`)
- Graph editor → Tauri commands: runs macro
- App shell → Tauri commands: invokes commands (evidence: `src/App.tsx`)
- Tauri commands → Graph engine: starts and stops (evidence: `src-tauri/src/main.rs`)
- Tauri commands → Macro folders: manages macro files (evidence: `src-tauri/src/main.rs`)
- Graph engine → Macro graph data: loads graph (evidence: `src-tauri/src/engine.rs`)
- Graph engine → Node dispatcher: dispatches nodes (evidence: `src-tauri/src/engine.rs`)
- Node dispatcher → Input and vision: performs input and scans (evidence: `src-tauri/src/nodes/mouse_drag.rs`)
- Node dispatcher → Script and IPC nodes: routes node types (evidence: `src-tauri/src/nodes/mod.rs`)
- Script and IPC nodes → AHK IPC: sends IPC
- User → App shell: requests force stop (evidence: `README.md`)
- App shell → Tauri commands: requests stop (evidence: `src/App.tsx`)
- App shell → Runtime logs: opens runtime logs (evidence: `src/App.tsx`)
- App shell → Update client: checks updates (evidence: `README.md`)
- Update client → GitHub Releases: checks releases (evidence: `README.md`)
