# sirantonysir/editor architecture

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

- Interactive diagram: https://gitdiagram.com/sirantonysir/editor
- Repository: https://github.com/sirantonysir/editor

## Overview

1. **Overall shape**
   - This is a **React + TypeScript photo editor** with a **Python backend** for AI-assisted features.
   - The core editing experience runs in the frontend; the backend is a separate service for analysis, refinement, segmentation, session APIs, and MCP exposure.
   - There is also an **Electron main/preload layer**, so the same app can be packaged as a desktop shell.

2. **Frontend presentation layer**
   - The UI is organized around a **canvas workspace** and a right-side **inspector**.
   - Main UI areas include: canvas/workspace, layers/panels, toolbar, command palette, inspector tabs, and widget editors.
   - The workspace renders image nodes, widget nodes, tether/overlay visuals, crop overlays, and segment/object indicators.

3. **Editor state and boundaries**
   - App state is split into **Zustand slices**: document, layers, selection, tool, viewport, workspace, backend status, segmentation, and suggestions UI.
   - Undo/redo is handled as part of the local editor state model, not by mutating pixels directly.
   - The key boundary is between **ephemeral UI state** in Zustand and **pixel data / session artifacts** stored elsewhere.

4. **Non-destructive image model**
   - The editor is built around **non-destructive editing**: adjustments are metadata, not baked into pixels.
   - Crop, layer transforms, masks, and widget parameters are all modeled as state attached to documents/layers/widgets.
   - Original or pre-crop image data is preserved so edits can be revisited and re-rendered.

5. **Render and processing pipeline**
   - Image rendering uses **Fabric.js** for canvas interaction plus a **custom WebGL shader pipeline** for filters/adjustments.
   - The rendering path is layered: each image/layer gets its own adjustment pipeline, then results are composited into the final output.
   - CPU-heavy work is offloaded through **workers** and pipeline helpers rather than being done directly in React render flow.

6. **Tool system**
   - Tools are modeled as **self-contained definitions** and discovered through a registry.
   - There are atomic tools for selection, masks, image context, widget ops, and analysis, plus **fused tools** that bundle multiple adjustment operations into higher-level editing actions.
   - This is an important architectural boundary: new editor capabilities are added by registering tool modules rather than wiring special cases throughout the app.

7. **Registry-driven adjustment library**
   - The project has a shared **registry of ops and presets** under `shared/registry`, consumed by both frontend and backend.
   - JSON schema files and generated shared types define the contract for operation graphs, widgets, contexts, and session snapshots.
   - The UI, tool manifests, and backend registry loader all depend on this common schema layer, which keeps the editor’s controls and AI tool surface consistent.

8. **AI-assisted editing loop**
   - The frontend has hooks for backend session status, image context, and auto-suggested actions.
   - The backend uses an **Anthropic client** and services for context assembly, autonomous suggestions, and refinement workflows.
   - Data flow is: image/document state → context extraction/analysis → backend suggestion/refinement → frontend UI updates and tool actions.

9. **Segmentation and object mode**
   - Objects-mode is powered by **SAM/MobileSAM** on the frontend and supported by backend segmentation endpoints.
   - The app manages masks, named regions, object extraction, region precomputation, and object ownership as first-class state.
   - This subsystem feeds both the workspace overlay and the inspector panels, and it also supports AI tools that need region-aware context.

10. **Session persistence and lifecycle**
   - Sessions are handled through a dedicated session layer with **history, checkpointers, persistence, revive, and migrations**.
   - There are both frontend persistence helpers and backend session APIs, suggesting a split between local editor continuity and server-backed AI/session continuity.
   - The architecture supports restoring editor state, undo/redo cycles, and migration from older snapshot formats.

11. **Backend service surface**
   - The Python backend exposes API modules for **analyze, refine, segment, session, state, telemetry, admin, panel, and tools REST**.
   - It also contains an **MCP server** and rate limiting, indicating it can act as a tool provider for external AI/agent workflows.
   - In diagram terms, the backend is not the rendering engine; it is the **analysis and orchestration boundary** around the editor.

12. **Shared contracts and validation**
   - `shared/schemas` and `shared/types` define the contract between frontend, backend, and generated tool manifests.
   - Tests are extensive across registry, session, state, tools, and contract boundaries, which reinforces that the architecture depends heavily on stable cross-layer schemas.
   - For an architecture diagram, the most important arrows are between: **document/layer state → render pipeline**, **image/context state → backend analysis**, and **registry schemas → UI/tool generation**.

Main entry points: [`backend/app/main.py`](https://github.com/sirantonysir/editor/blob/main/backend/app/main.py) (API surface), [`src/store/index.ts`](https://github.com/sirantonysir/editor/blob/main/src/store/index.ts) (Editor state), [`src/main.tsx`](https://github.com/sirantonysir/editor/blob/main/src/main.tsx) (App shell), [`src/core/document.ts`](https://github.com/sirantonysir/editor/blob/main/src/core/document.ts) (Doc model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend app"]
  node_app_shell["App shell<br/>React entry<br/>[main.tsx]"]
  node_workspace_ui["Workspace<br/>canvas UI"]
  node_inspector_ui["Inspector<br/>sidebar UI<br/>[InspectorPanel.tsx]"]
  node_toolbar_ui["Toolbar<br/>command UI<br/>[MenuBar.tsx]"]
  node_store[("Editor state<br/>Zustand slices<br/>[index.ts]")]
  node_document_model["Doc model<br/>non-destructive state<br/>[document.ts]"]
  node_history_persistence[("History & save<br/>session continuity")]
  node_render_pipeline["Render pipeline<br/>canvas rendering"]
  node_shaders["Shaders<br/>WebGL filters<br/>[pipeline.ts]"]
  node_workers["Workers<br/>background processing"]
  node_tool_system["Tool system<br/>tool registry<br/>[registry.ts]"]
  node_registry_ui["Registry UI<br/>schema-driven controls<br/>[index.ts]"]
  node_segmentation["Segmentation<br/>object mode"]
  node_ai_hooks["AI hooks<br/>backend integration"]
end

subgraph group_backend["Backend service"]
  node_backend_api["API surface<br/>FastAPI modules<br/>[main.py]"]
  node_backend_services["AI services<br/>orchestration"]
  node_backend_session[("Session engine<br/>session lifecycle<br/>[persistence.py]")]
  node_backend_registry["Registry backend<br/>shared resolver<br/>[loader.py]"]
  node_backend_state["Backend state<br/>document/session state<br/>[document.py]"]
end

subgraph group_shared["Shared contracts"]
  node_shared_registry["Shared registry<br/>ops/presets<br/>[schema.ts]"]
  node_shared_schemas["Shared schemas<br/>contracts"]
end

subgraph group_desktop["Desktop shell"]
  node_electron_shell["Electron shell<br/>desktop bridge<br/>[main.cjs]"]
end

node_app_shell -->|"mounts"| node_workspace_ui
node_app_shell -->|"mounts"| node_inspector_ui
node_app_shell -->|"mounts"| node_toolbar_ui
node_workspace_ui -->|"reads state"| node_store
node_inspector_ui -->|"reads state"| node_store
node_toolbar_ui -->|"dispatches"| node_store
node_store -->|"hosts"| node_document_model
node_document_model -->|"snapshots"| node_history_persistence
node_document_model -->|"renders"| node_render_pipeline
node_render_pipeline -->|"uses"| node_shaders
node_render_pipeline -->|"offloads"| node_workers
node_tool_system -->|"updates"| node_store
node_registry_ui -->|"binds to"| node_shared_schemas
node_registry_ui -->|"reads"| node_shared_registry
node_tool_system -->|"discovers tools"| node_shared_registry
node_segmentation -->|"writes masks"| node_store
node_ai_hooks -->|"calls"| node_backend_api
node_backend_api -->|"orchestrates"| node_backend_services
node_backend_api -->|"persists"| node_backend_session
node_backend_api -->|"serves state"| node_backend_state
node_backend_services -->|"resolves ops"| node_backend_registry
node_backend_registry -->|"loads from"| node_shared_registry
node_backend_state -->|"validates against"| node_shared_schemas
node_backend_api -->|"contracts"| node_shared_schemas
node_electron_shell -->|"hosts"| node_app_shell
node_electron_shell -->|"bridges to"| node_backend_api

click node_app_shell "https://github.com/sirantonysir/editor/blob/main/src/main.tsx"
click node_workspace_ui "https://github.com/sirantonysir/editor/blob/main/src/components/workspace/CanvasWorkspace.tsx"
click node_inspector_ui "https://github.com/sirantonysir/editor/blob/main/src/components/inspector/InspectorPanel.tsx"
click node_toolbar_ui "https://github.com/sirantonysir/editor/blob/main/src/components/toolbar/MenuBar.tsx"
click node_store "https://github.com/sirantonysir/editor/blob/main/src/store/index.ts"
click node_document_model "https://github.com/sirantonysir/editor/blob/main/src/core/document.ts"
click node_history_persistence "https://github.com/sirantonysir/editor/blob/main/src/core/editor-state-persistence.ts"
click node_render_pipeline "https://github.com/sirantonysir/editor/blob/main/src/lib/image-node-renderer.ts"
click node_shaders "https://github.com/sirantonysir/editor/blob/main/src/shaders/pipeline.ts"
click node_workers "https://github.com/sirantonysir/editor/blob/main/src/workers/processing.worker.ts"
click node_tool_system "https://github.com/sirantonysir/editor/blob/main/src/engine/registry.ts"
click node_registry_ui "https://github.com/sirantonysir/editor/blob/main/src/lib/tool-manifest/index.ts"
click node_segmentation "https://github.com/sirantonysir/editor/blob/main/src/lib/segmentation/mobile-sam-client.ts"
click node_ai_hooks "https://github.com/sirantonysir/editor/blob/main/src/hooks/useAutoTetherAiSuggestions.ts"
click node_backend_api "https://github.com/sirantonysir/editor/blob/main/backend/app/main.py"
click node_backend_services "https://github.com/sirantonysir/editor/blob/main/backend/app/services/anthropic_client.py"
click node_backend_session "https://github.com/sirantonysir/editor/blob/main/backend/app/session/persistence.py"
click node_backend_registry "https://github.com/sirantonysir/editor/blob/main/backend/app/registry/loader.py"
click node_backend_state "https://github.com/sirantonysir/editor/blob/main/backend/app/state/document.py"
click node_shared_registry "https://github.com/sirantonysir/editor/blob/main/shared/registry/schema.ts"
click node_shared_schemas "https://github.com/sirantonysir/editor/blob/main/shared/schemas/combined.schema.json"
click node_electron_shell "https://github.com/sirantonysir/editor/blob/main/electron/main.cjs"

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_shell,node_workspace_ui,node_inspector_ui,node_toolbar_ui,node_store,node_document_model,node_history_persistence,node_render_pipeline,node_shaders,node_workers,node_tool_system,node_registry_ui,node_segmentation,node_ai_hooks toneBlue
class node_backend_api,node_backend_services,node_backend_session,node_backend_registry,node_backend_state toneAmber
class node_shared_registry,node_shared_schemas toneMint
class node_electron_shell toneRose
```

## Components

### Frontend app

React + TypeScript editor UI, state, rendering, and local processing.

- [App shell](https://github.com/sirantonysir/editor/blob/main/src/main.tsx): React entry · Bootstraps the editor and top-level providers. · `src/main.tsx`
- [Workspace](https://github.com/sirantonysir/editor/blob/main/src/components/workspace/CanvasWorkspace.tsx): canvas UI · Canvas-centric editing surface for image nodes, widgets, overlays, and tethers. · `src/components/workspace/CanvasWorkspace.tsx`
- [Inspector](https://github.com/sirantonysir/editor/blob/main/src/components/inspector/InspectorPanel.tsx): sidebar UI · Right-side panel for layers, crop, info, adjustments, and widget editing. · `src/components/inspector/InspectorPanel.tsx`
- [Toolbar](https://github.com/sirantonysir/editor/blob/main/src/components/toolbar/MenuBar.tsx): command UI · History, menu actions, shortcuts, and command palette entry points. · `src/components/toolbar/MenuBar.tsx`
- [Editor state](https://github.com/sirantonysir/editor/blob/main/src/store/index.ts): Zustand slices · Document, layers, selection, tool, viewport, workspace, backend, segmentation, and suggestions state. · `src/store/index.ts`
- [Doc model](https://github.com/sirantonysir/editor/blob/main/src/core/document.ts): non-destructive state · Document, layer, widget, crop, mask, and transform metadata used for undoable editing. · `src/core/document.ts`
- [History & save](https://github.com/sirantonysir/editor/blob/main/src/core/editor-state-persistence.ts): session continuity · Undo/redo, persistence, restore, and pixel source/session lifecycle helpers. · `src/core/editor-state-persistence.ts`
- [Render pipeline](https://github.com/sirantonysir/editor/blob/main/src/lib/image-node-renderer.ts): canvas rendering · Compositing and per-layer rendering path combining Fabric.js interaction with shader-based processing. · `src/lib/image-node-renderer.ts`
- [Shaders](https://github.com/sirantonysir/editor/blob/main/src/shaders/pipeline.ts): WebGL filters · GPU adjustment and blend shaders for image processing. · `src/shaders/pipeline.ts`
- [Workers](https://github.com/sirantonysir/editor/blob/main/src/workers/processing.worker.ts): background processing · Offloads CPU-heavy processing and pipeline work from the React flow. · `src/workers/processing.worker.ts`
- [Tool system](https://github.com/sirantonysir/editor/blob/main/src/engine/registry.ts): tool registry · Self-contained tools and toolrail behavior for selection, masks, analysis, and fused actions. · `src/engine/registry.ts`
- [Registry UI](https://github.com/sirantonysir/editor/blob/main/src/lib/tool-manifest/index.ts): schema-driven controls · Inspector controls, widget shells, and tool manifests generated from shared registry definitions. · `src/lib/tool-manifest/index.ts`
- [Segmentation](https://github.com/sirantonysir/editor/blob/main/src/lib/segmentation/mobile-sam-client.ts): object mode · SAM/MobileSAM-backed selection, masks, regions, and object ownership flows. · `src/lib/segmentation/mobile-sam-client.ts`
- [AI hooks](https://github.com/sirantonysir/editor/blob/main/src/hooks/useAutoTetherAiSuggestions.ts): backend integration · Frontend hooks for session status, image context, and auto-suggested actions. · `src/hooks/useAutoTetherAiSuggestions.ts`

### Backend service

Python AI and session orchestration service.

- [API surface](https://github.com/sirantonysir/editor/blob/main/backend/app/main.py): FastAPI modules · Analyze, refine, segment, session, state, telemetry, admin, panel, and tools REST endpoints. · `backend/app/main.py`
- [AI services](https://github.com/sirantonysir/editor/blob/main/backend/app/services/anthropic_client.py): orchestration · Anthropic client, LLM context assembly, autonomous suggestions, image validation, and SAM client. · `backend/app/services/anthropic_client.py`
- [Session engine](https://github.com/sirantonysir/editor/blob/main/backend/app/session/persistence.py): session lifecycle · History, checkpoints, persistence, revive, disk I/O, and migrations for session continuity. · `backend/app/session/persistence.py`
- [Registry backend](https://github.com/sirantonysir/editor/blob/main/backend/app/registry/loader.py): shared resolver · Loads, interpolates, and resolves registry ops, presets, and schema contracts. · `backend/app/registry/loader.py`
- [Backend state](https://github.com/sirantonysir/editor/blob/main/backend/app/state/document.py): document/session state · Canonical document state, snapshots, events, and preview rendering for server-side workflows. · `backend/app/state/document.py`

### Shared contracts

Registry, schemas, and generated types shared across runtimes.

- [Shared registry](https://github.com/sirantonysir/editor/blob/main/shared/registry/schema.ts): ops/presets · Common adjustment ops and presets consumed by both frontend and backend. · `shared/registry/schema.ts`
- [Shared schemas](https://github.com/sirantonysir/editor/blob/main/shared/schemas/combined.schema.json): contracts · JSON schemas and generated types for contexts, widgets, operation graphs, and session snapshots. · `shared/schemas/combined.schema.json`

### Desktop shell

Electron main and preload layer.

- [Electron shell](https://github.com/sirantonysir/editor/blob/main/electron/main.cjs): desktop bridge · Desktop main and preload process for packaging the app as a shell. · `electron/main.cjs`

## Connections

- App shell → Workspace: mounts · Renders the main editing canvas.
- App shell → Inspector: mounts · Renders the side inspector.
- App shell → Toolbar: mounts · Provides top-level actions and shortcuts.
- Workspace → Editor state: reads state · Consumes document, selection, tool, viewport, and workspace slices.
- Inspector → Editor state: reads state · Consumes layer, segmentation, suggestions, and backend status slices.
- Toolbar → Editor state: dispatches · Triggers history, palette, and tool actions.
- Editor state → Doc model: hosts · Keeps the non-destructive editor model in local state.
- Doc model → History & save: snapshots · Document changes feed undo/redo and persistence.
- Doc model → Render pipeline: renders · Layer, crop, widget, and mask state drives compositing.
- Render pipeline → Shaders: uses · Applies GPU adjustment and blending stages.
- Render pipeline → Workers: offloads · Sends heavy processing away from React render flow.
- Tool system → Editor state: updates · Tools mutate editor state through controlled actions.
- Registry UI → Shared schemas: binds to · Builds controls from shared schemas and types.
- Registry UI → Shared registry: reads · Uses the common adjustment/preset registry.
- Tool system → Shared registry: discovers tools · Tool manifests and fused actions are registry-driven.
- Segmentation → Editor state: writes masks · Updates object mode, regions, and selection state.
- AI hooks → API surface: calls · Requests session status, analysis, refine, and suggestions.
- API surface → AI services: orchestrates · Routes requests into AI and analysis services.
- API surface → Session engine: persists · Creates, restores, checkpoints, and revives sessions.
- API surface → Backend state: serves state · Exposes canonical document and preview data.
- AI services → Registry backend: resolves ops · Uses registry data to assemble analysis and refinement workflows.
- Registry backend → Shared registry: loads from · Shares the op and preset definitions with the frontend.
- Backend state → Shared schemas: validates against · Uses shared schemas for snapshots and operation graphs.
- API surface → Shared schemas: contracts · API payloads are shaped by the shared schema layer.
- Electron shell → App shell: hosts · Wraps the frontend as a desktop app.
- Electron shell → API surface: bridges to · Desktop packaging can talk to the backend service.