# katkurigopi05/photo-editor architecture

> Architecture diagram of the GitHub repository katkurigopi05/photo-editor, 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/katkurigopi05/photo-editor
- Repository: https://github.com/katkurigopi05/photo-editor
- Video tour (about a minute): https://gitdiagram.com/katkurigopi05/photo-editor/video

## Overview

Project Director and photo-editor are parallel non-destructive editor tracks: a TypeScript/Rust web-and-desktop-oriented editor and a Python GUI/CLI editor. In the browser workflow, users edit a project through the web app, which dispatches validated commands into replayable editor state and supports media import, playback, and export. The Python workflow opens media as a document, applies serializable operations, and exports images or frame-based media. The README documents additional AI, CV, video, and MCP capabilities. Some TypeScript and Rust links reflect documented capabilities rather than inspected runtime wiring.

Main entry points: [`apps/web/src/main.ts`](https://github.com/katkurigopi05/photo-editor/blob/main/apps/web/src/main.ts) (Browser editor), [`packages/editor-state/src/engine.ts`](https://github.com/katkurigopi05/photo-editor/blob/main/packages/editor-state/src/engine.ts) (Operation engine), [`app.py`](https://github.com/katkurigopi05/photo-editor/blob/main/app.py) (Python CLI), [`core/operations.py`](https://github.com/katkurigopi05/photo-editor/blob/main/core/operations.py) (Image operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web editor"]
  node_web_app["Browser editor<br/>[main.ts]"]
  node_ui["Timeline UI<br/>[drag.ts]"]
  node_playback["Playback"]
  node_tracking["Motion tracking"]
end

subgraph group_state["Project core"]
  node_schema["Project schema"]
  node_commands["Command validation<br/>[public-commands.ts]"]
  node_engine["Operation engine<br/>[engine.ts]"]
  node_reducers["Project reducers<br/>[reducers.ts]"]
  node_canonical["Canonical serialization<br/>[index.ts]"]
  node_project_store[("Project persistence<br/>[lib.rs]")]
end

subgraph group_media["Media capabilities"]
  node_media_decode["Media decoding<br/>[decode.rs]"]
  node_raw_decode["RAW decoding<br/>[route.ts]"]
  node_raster["Raster effects<br/>[adjust.ts]"]
  node_segmentation["Background segmentation<br/>[inference.ts]"]
  node_export["Export jobs<br/>[plan.ts]"]
  node_audio["Audio engine<br/>[lib.rs]"]
  node_timeline["Timeline engine<br/>[lib.rs]"]
end

subgraph group_python["Python editor"]
  node_cli["Python CLI<br/>[app.py]"]
  node_gui["Python GUI<br/>[photo_editor.py]"]
  node_document["Edit document<br/>[document.py]"]
  node_operations["Image operations<br/>[operations.py]"]
  node_builder["Frame builder<br/>[builder.py]"]
  node_video["Video processing<br/>[processing.py]"]
  node_ai_ops["AI operations<br/>[operations.py]"]
  node_cv_ops["CV operations<br/>[operations.py]"]
end

subgraph group_services["Automation"]
  node_mcp_server["MCP tools<br/>[edit.ts]"]
  node_mcp_session["MCP project session<br/>[session.ts]"]
  node_mcp_store[("MCP project files<br/>[project-store.ts]")]
end

node_web_user(("Editor user"))
node_python_user(("Photo editor user"))
node_mcp_user(("MCP client"))

node_web_user -->|"edits in"| node_web_app
node_web_app -->|"uses timeline gestures"| node_ui
node_web_app -->|"resolves playback"| node_playback
node_web_app -->|"uses tracking"| node_tracking
node_web_app -.->|"dispatches commands"| node_engine
node_ui -->|"builds command payloads"| node_commands
node_engine -->|"validates commands"| node_commands
node_engine -->|"applies commands"| node_reducers
node_engine -->|"serializes operations"| node_canonical
node_reducers -->|"uses project types"| node_schema
node_web_app -.->|"routes RAW imports"| node_raw_decode
node_web_app -.->|"starts exports"| node_export
node_web_app -.->|"decodes media"| node_media_decode
node_web_app -.->|"applies image effects"| node_raster
node_web_app -.->|"offers segmentation"| node_segmentation
node_web_app -.->|"supports audio"| node_audio
node_web_app -.->|"uses timeline core"| node_timeline
node_engine -.->|"persists project state"| node_project_store
node_python_user -->|"edits media"| node_gui
node_python_user -->|"runs recipes"| node_cli
node_cli -.->|"applies image recipe"| node_document
node_cli -->|"builds GIF or video"| node_builder
node_cli -->|"dispatches video edits"| node_video
node_gui -.->|"edits document"| node_document
node_document -->|"renders operations"| node_operations
node_builder -.->|"applies recipe operations"| node_operations
node_video -->|"uses frame builder"| node_builder
node_ai_ops -->|"extends operations"| node_operations
node_cv_ops -->|"extends operations"| node_operations
node_mcp_user -.->|"requests edits"| node_mcp_server
node_mcp_server -.->|"dispatches tool actions"| node_mcp_session
node_mcp_session -->|"dispatches commands"| node_engine
node_mcp_session -->|"loads and saves"| node_mcp_store

click node_web_app "https://github.com/katkurigopi05/photo-editor/blob/main/apps/web/src/main.ts"
click node_ui "https://github.com/katkurigopi05/photo-editor/blob/main/packages/ui-kit/src/drag.ts"
click node_playback "https://github.com/katkurigopi05/photo-editor/tree/main/packages/playback-controller/src"
click node_tracking "https://github.com/katkurigopi05/photo-editor/tree/main/packages/motion-tracking/src"
click node_schema "https://github.com/katkurigopi05/photo-editor/tree/main/packages/project-schema/src"
click node_commands "https://github.com/katkurigopi05/photo-editor/blob/main/packages/command-schema/src/public-commands.ts"
click node_engine "https://github.com/katkurigopi05/photo-editor/blob/main/packages/editor-state/src/engine.ts"
click node_reducers "https://github.com/katkurigopi05/photo-editor/blob/main/packages/editor-state/src/reducers.ts"
click node_canonical "https://github.com/katkurigopi05/photo-editor/blob/main/packages/canonical-json/src/index.ts"
click node_project_store "https://github.com/katkurigopi05/photo-editor/blob/main/crates/project-store/src/lib.rs"
click node_media_decode "https://github.com/katkurigopi05/photo-editor/blob/main/crates/media-core/src/decode.rs"
click node_raw_decode "https://github.com/katkurigopi05/photo-editor/blob/main/packages/raw-decode/src/route.ts"
click node_raster "https://github.com/katkurigopi05/photo-editor/blob/main/packages/raster-tools/src/adjust.ts"
click node_segmentation "https://github.com/katkurigopi05/photo-editor/blob/main/packages/bg-segmentation/src/inference.ts"
click node_export "https://github.com/katkurigopi05/photo-editor/blob/main/packages/export-engine/src/plan.ts"
click node_audio "https://github.com/katkurigopi05/photo-editor/blob/main/crates/audio-engine/src/lib.rs"
click node_timeline "https://github.com/katkurigopi05/photo-editor/blob/main/crates/timeline-engine/src/lib.rs"
click node_cli "https://github.com/katkurigopi05/photo-editor/blob/main/app.py"
click node_gui "https://github.com/katkurigopi05/photo-editor/blob/main/photo_editor.py"
click node_document "https://github.com/katkurigopi05/photo-editor/blob/main/core/document.py"
click node_operations "https://github.com/katkurigopi05/photo-editor/blob/main/core/operations.py"
click node_builder "https://github.com/katkurigopi05/photo-editor/blob/main/core/builder.py"
click node_video "https://github.com/katkurigopi05/photo-editor/blob/main/video_tools/processing.py"
click node_ai_ops "https://github.com/katkurigopi05/photo-editor/blob/main/ai_tools/operations.py"
click node_cv_ops "https://github.com/katkurigopi05/photo-editor/blob/main/cv_tools/operations.py"
click node_mcp_server "https://github.com/katkurigopi05/photo-editor/blob/main/packages/mcp-server/src/tools/edit.ts"
click node_mcp_session "https://github.com/katkurigopi05/photo-editor/blob/main/packages/mcp-server/src/session.ts"
click node_mcp_store "https://github.com/katkurigopi05/photo-editor/blob/main/packages/mcp-server/src/project-store.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_web_app,node_ui,node_playback,node_tracking,node_web_user,node_python_user,node_mcp_user toneBlue
class node_schema,node_commands,node_engine,node_reducers,node_canonical,node_project_store toneAmber
class node_media_decode,node_raw_decode,node_raster,node_segmentation,node_export,node_audio,node_timeline toneMint
class node_cli,node_gui,node_document,node_operations,node_builder,node_video,node_ai_ops,node_cv_ops toneRose
class node_mcp_server,node_mcp_session,node_mcp_store toneIndigo
```

## Components

### Web editor

- [Browser editor](https://github.com/katkurigopi05/photo-editor/blob/main/apps/web/src/main.ts): `apps/web/src/main.ts`
- [Timeline UI](https://github.com/katkurigopi05/photo-editor/blob/main/packages/ui-kit/src/drag.ts): `packages/ui-kit/src/drag.ts`
- [Playback](https://github.com/katkurigopi05/photo-editor/tree/main/packages/playback-controller/src): `packages/playback-controller/src`
- [Motion tracking](https://github.com/katkurigopi05/photo-editor/tree/main/packages/motion-tracking/src): `packages/motion-tracking/src`

### Project core

- [Project schema](https://github.com/katkurigopi05/photo-editor/tree/main/packages/project-schema/src): `packages/project-schema/src`
- [Command validation](https://github.com/katkurigopi05/photo-editor/blob/main/packages/command-schema/src/public-commands.ts): `packages/command-schema/src/public-commands.ts`
- [Operation engine](https://github.com/katkurigopi05/photo-editor/blob/main/packages/editor-state/src/engine.ts): `packages/editor-state/src/engine.ts`
- [Project reducers](https://github.com/katkurigopi05/photo-editor/blob/main/packages/editor-state/src/reducers.ts): `packages/editor-state/src/reducers.ts`
- [Canonical serialization](https://github.com/katkurigopi05/photo-editor/blob/main/packages/canonical-json/src/index.ts): `packages/canonical-json/src/index.ts`
- [Project persistence](https://github.com/katkurigopi05/photo-editor/blob/main/crates/project-store/src/lib.rs): `crates/project-store/src/lib.rs`

### Media capabilities

- [Media decoding](https://github.com/katkurigopi05/photo-editor/blob/main/crates/media-core/src/decode.rs): `crates/media-core/src/decode.rs`
- [RAW decoding](https://github.com/katkurigopi05/photo-editor/blob/main/packages/raw-decode/src/route.ts): `packages/raw-decode/src/route.ts`
- [Raster effects](https://github.com/katkurigopi05/photo-editor/blob/main/packages/raster-tools/src/adjust.ts): `packages/raster-tools/src/adjust.ts`
- [Background segmentation](https://github.com/katkurigopi05/photo-editor/blob/main/packages/bg-segmentation/src/inference.ts): `packages/bg-segmentation/src/inference.ts`
- [Export jobs](https://github.com/katkurigopi05/photo-editor/blob/main/packages/export-engine/src/plan.ts): `packages/export-engine/src/plan.ts`
- [Audio engine](https://github.com/katkurigopi05/photo-editor/blob/main/crates/audio-engine/src/lib.rs): `crates/audio-engine/src/lib.rs`
- [Timeline engine](https://github.com/katkurigopi05/photo-editor/blob/main/crates/timeline-engine/src/lib.rs): `crates/timeline-engine/src/lib.rs`

### Python editor

- [Python CLI](https://github.com/katkurigopi05/photo-editor/blob/main/app.py): `app.py`
- [Python GUI](https://github.com/katkurigopi05/photo-editor/blob/main/photo_editor.py): `photo_editor.py`
- [Edit document](https://github.com/katkurigopi05/photo-editor/blob/main/core/document.py): `core/document.py`
- [Image operations](https://github.com/katkurigopi05/photo-editor/blob/main/core/operations.py): `core/operations.py`
- [Frame builder](https://github.com/katkurigopi05/photo-editor/blob/main/core/builder.py): `core/builder.py`
- [Video processing](https://github.com/katkurigopi05/photo-editor/blob/main/video_tools/processing.py): `video_tools/processing.py`
- [AI operations](https://github.com/katkurigopi05/photo-editor/blob/main/ai_tools/operations.py): `ai_tools/operations.py`
- [CV operations](https://github.com/katkurigopi05/photo-editor/blob/main/cv_tools/operations.py): `cv_tools/operations.py`

### Automation

- [MCP tools](https://github.com/katkurigopi05/photo-editor/blob/main/packages/mcp-server/src/tools/edit.ts): `packages/mcp-server/src/tools/edit.ts`
- [MCP project session](https://github.com/katkurigopi05/photo-editor/blob/main/packages/mcp-server/src/session.ts): `packages/mcp-server/src/session.ts`
- [MCP project files](https://github.com/katkurigopi05/photo-editor/blob/main/packages/mcp-server/src/project-store.ts): `packages/mcp-server/src/project-store.ts`

### Other components

- **Editor user**
- **Photo editor user**
- **MCP client**

## Connections

- Editor user → Browser editor: edits in (evidence: `README.md`)
- Browser editor → Timeline UI: uses timeline gestures (evidence: `apps/web/src/main.ts`)
- Browser editor → Playback: resolves playback (evidence: `apps/web/src/main.ts`)
- Browser editor → Motion tracking: uses tracking (evidence: `apps/web/src/main.ts`)
- Browser editor → Operation engine: dispatches commands
- Timeline UI → Command validation: builds command payloads (evidence: `packages/ui-kit/src/drag.ts`)
- Operation engine → Command validation: validates commands (evidence: `packages/editor-state/src/engine.ts`)
- Operation engine → Project reducers: applies commands (evidence: `packages/editor-state/src/engine.ts`)
- Operation engine → Canonical serialization: serializes operations (evidence: `packages/editor-state/src/engine.ts`)
- Project reducers → Project schema: uses project types (evidence: `packages/editor-state/src/reducers.ts`)
- Browser editor → RAW decoding: routes RAW imports
- Browser editor → Export jobs: starts exports
- Browser editor → Media decoding: decodes media
- Browser editor → Raster effects: applies image effects
- Browser editor → Background segmentation: offers segmentation
- Browser editor → Audio engine: supports audio
- Browser editor → Timeline engine: uses timeline core
- Operation engine → Project persistence: persists project state
- Photo editor user → Python GUI: edits media (evidence: `README.md`)
- Photo editor user → Python CLI: runs recipes (evidence: `README.md`)
- Python CLI → Edit document: applies image recipe (evidence: `app.py`)
- Python CLI → Frame builder: builds GIF or video (evidence: `app.py`)
- Python CLI → Video processing: dispatches video edits (evidence: `app.py`)
- Python GUI → Edit document: edits document
- Edit document → Image operations: renders operations (evidence: `core/document.py`)
- Frame builder → Image operations: applies recipe operations
- Video processing → Frame builder: uses frame builder (evidence: `video_tools/processing.py`)
- AI operations → Image operations: extends operations (evidence: `ai_tools/operations.py`)
- CV operations → Image operations: extends operations (evidence: `cv_tools/operations.py`)
- MCP client → MCP tools: requests edits
- MCP tools → MCP project session: dispatches tool actions
- MCP project session → Operation engine: dispatches commands (evidence: `packages/mcp-server/src/session.ts`)
- MCP project session → MCP project files: loads and saves (evidence: `packages/mcp-server/src/session.ts`)
