# comfy-org/comfyui-embedded-workflow-editor architecture

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

- Interactive diagram: https://gitdiagram.com/comfy-org/comfyui-embedded-workflow-editor
- Repository: https://github.com/comfy-org/comfyui-embedded-workflow-editor

## Overview

1. **What this repo is**
   - A single **Next.js + Bun** application for editing **ComfyUI workflow JSON embedded inside media files**.
   - It is **browser-first**: there is no database or long-lived backend service. The app loads a file, decodes embedded workflow data, lets the user edit it, then re-embeds/saves it.

2. **Primary user-facing app**
   - `app/page.tsx` is the main editor entry point, with `app/layout.tsx`, `app/globals.css`, and `app/fonts` providing the shell and styling.
   - The UI is centered around opening media, showing a preview, exposing the embedded workflow, and saving the edited file.

3. **State management boundary**
   - `app/uiState.tsx` and `app/persistState.tsx` indicate the editor state is managed in client-side state providers.
   - This is where file selection, current workflow JSON, preview state, and edit/session persistence live, rather than in a server store.

4. **Media ingestion paths**
   - The app supports multiple ways to load content:
     - local upload,
     - mounting a local directory,
     - direct URL input / `?url=...` loading.
   - `app/types/file-system-access.d.ts` shows explicit support for the **File System Access API** for local directory workflows.

5. **Server-side media fetch/proxy layer**
   - `app/api/media/route.ts` plus `app/api/media/detectContentType.ts` form the server boundary for media loading.
   - This layer likely handles fetching remote files, normalizing responses, and detecting the true MIME/content type before the browser-side codec layer processes bytes.

6. **Format-specific metadata codec layer**
   - The core binary work lives in `app/utils/`.
   - There is a shared dispatcher in `exif.ts`, with format-specific readers/writers for:
     - `exif-png.ts`
     - `exif-webp.ts`
     - `exif-flac.ts`
     - `exif-mp3.ts`
     - `exif-mp4.ts`
   - `encodeTIFFBlock.ts` and `utils.ts` are shared low-level helpers for binary chunk assembly and parsing.

7. **Supported media formats**
   - The architecture is organized around **container-specific metadata embedding** for:
     - PNG
     - WEBP
     - FLAC
     - MP3
     - MP4
   - The editor extracts the embedded ComfyUI workflow from each format’s metadata structure, edits it as JSON, then writes it back into the same container type.

8. **Output/save flow**
   - The runtime data flow is: **bytes in → detect format → extract workflow → edit in UI → re-encode bytes → save/download**.
   - This means the app’s critical correctness boundary is the round-trip between raw media bytes and embedded workflow metadata.

9. **Validation strategy**
   - Each codec has companion tests under `app/utils/*.test.ts`.
   - Integration fixtures live in `tests/` with real sample media and workflow JSON sidecars, including malformed cases for WEBP.
   - This makes format parsing and re-embedding the main testable subsystem, not the UI.

10. **Runtime/tooling/infrastructure**
   - The project uses **Bun** for development and CI (`.github/workflows/bun-test.yml`).
   - **Tailwind/PostCSS** handle styling; **Next.js** provides the app router and API routes.
   - `middleware.ts` and `next.config.ts` define request/runtime behavior at the framework boundary, while GitHub Actions enforce tests and formatting.

11. **What is intentionally absent**
   - No database, message queue, auth service, or separate backend API.
   - The architecture is essentially **client editor + thin server fetch/type-detection layer + binary codec library**.

12. **How to draw it**
   - A good diagram would show:
     - user/browser UI on the left,
     - an API/media fetch boundary in the middle,
     - a shared parsing/encoding library underneath,
     - and container-specific codecs branching out for PNG/WEBP/FLAC/MP3/MP4.
   - The main architectural concern is preserving exact media bytes while editing embedded workflow metadata.

Main entry points: [`app/utils/exif.ts`](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif.ts) (Dispatcher), [`app/utils/exif-png.test.ts`](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-png.test.ts) (Codec Tests), [`app/page.tsx`](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/page.tsx) (Editor), [`app/layout.tsx`](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/layout.tsx) (App Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Browser App"]
  node_n1["Editor<br/>Next.js page<br/>[page.tsx]"]
  node_n2["App Shell<br/>layout<br/>[layout.tsx]"]
  node_n3["Styles<br/>global css<br/>[globals.css]"]
  node_n4["Font Assets"]
  node_n5["UI State<br/>client state<br/>[uiState.tsx]"]
  node_n6["Persist State<br/>client persistence<br/>[persistState.tsx]"]
  node_n7["File Access API<br/>browser typings"]
end

subgraph group_g2["Server Boundary"]
  node_n8["Media API<br/>Next route<br/>[route.ts]"]
  node_n9["Content Type<br/>detect helper"]
end

subgraph group_g3["Codec Library"]
  node_n10["Dispatcher<br/>codec router<br/>[exif.ts]"]
  node_n11["Binary Utils<br/>helpers<br/>[utils.ts]"]
  node_n12["TIFF Encode<br/>binary builder<br/>[encodeTIFFBlock.ts]"]
  node_n13["PNG Codec<br/>container codec<br/>[exif-png.ts]"]
  node_n14["WEBP Codec<br/>container codec<br/>[exif-webp.ts]"]
  node_n15["FLAC Codec<br/>container codec<br/>[exif-flac.ts]"]
  node_n16["MP3 Codec<br/>container codec<br/>[exif-mp3.ts]"]
  node_n17["MP4 Codec<br/>container codec<br/>[exif-mp4.ts]"]
end

subgraph group_g4["Validation"]
  node_n18["Codec Tests<br/>unit tests<br/>[exif-png.test.ts]"]
  node_n19["Fixture Media<br/>integration fixtures"]
end

subgraph group_g5["Tooling"]
  node_n20["Bun CI<br/>workflow<br/>[bun-test.yml]"]
  node_n21["Framework Config<br/>next config<br/>[next.config.ts]"]
  node_n22["Middleware<br/>[middleware.ts]"]
end

node_n1 -->|"uses"| node_n5
node_n1 -->|"persists"| node_n6
node_n1 -->|"loads dirs"| node_n7
node_n1 -->|"fetches media"| node_n8
node_n2 -->|"hosts"| node_n1
node_n2 -->|"applies"| node_n3
node_n2 -->|"includes"| node_n4
node_n8 -->|"detects"| node_n9
node_n8 -->|"feeds"| node_n10
node_n10 -->|"routes png"| node_n13
node_n10 -->|"routes webp"| node_n14
node_n10 -->|"routes flac"| node_n15
node_n10 -->|"routes mp3"| node_n16
node_n10 -->|"routes mp4"| node_n17
node_n13 -->|"uses"| node_n11
node_n14 -->|"uses"| node_n11
node_n15 -->|"uses"| node_n12
node_n16 -->|"uses"| node_n11
node_n17 -->|"uses"| node_n12
node_n13 -.->|"verified by"| node_n18
node_n14 -.->|"verified by"| node_n18
node_n15 -.->|"verified by"| node_n18
node_n16 -.->|"verified by"| node_n18
node_n17 -.->|"verified by"| node_n18
node_n10 -.->|"validated by"| node_n19
node_n20 -->|"runs"| node_n18
node_n20 -->|"checks"| node_n19
node_n21 -->|"configures"| node_n2
node_n22 -->|"guards"| node_n8

click node_n1 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/page.tsx"
click node_n2 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/layout.tsx"
click node_n3 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/globals.css"
click node_n4 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/tree/main/app/fonts"
click node_n5 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/uiState.tsx"
click node_n6 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/persistState.tsx"
click node_n7 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/types/file-system-access.d.ts"
click node_n8 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/api/media/route.ts"
click node_n9 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/api/media/detectContentType.ts"
click node_n10 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif.ts"
click node_n11 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/utils.ts"
click node_n12 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/encodeTIFFBlock.ts"
click node_n13 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-png.ts"
click node_n14 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-webp.ts"
click node_n15 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-flac.ts"
click node_n16 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-mp3.ts"
click node_n17 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-mp4.ts"
click node_n18 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-png.test.ts"
click node_n19 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/tree/main/tests"
click node_n20 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/.github/workflows/bun-test.yml"
click node_n21 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/next.config.ts"
click node_n22 "https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/middleware.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_n1,node_n2,node_n3,node_n4,node_n5,node_n6,node_n7 toneBlue
class node_n8,node_n9 toneAmber
class node_n10,node_n11,node_n12,node_n13,node_n14,node_n15,node_n16,node_n17 toneMint
class node_n18,node_n19 toneRose
class node_n20,node_n21,node_n22 toneIndigo
```

## Components

### Browser App

Client-side editor shell, state, and file-loading UX.

- [Editor](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/page.tsx): Next.js page · Main browser editor entry point for opening, previewing, editing, and saving embedded workflows. · `app/page.tsx`
- [App Shell](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/layout.tsx): layout · Top-level document shell and global app structure. · `app/layout.tsx`
- [Styles](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/globals.css): global css · Global styling and visual baseline for the editor. · `app/globals.css`
- [Font Assets](https://github.com/comfy-org/comfyui-embedded-workflow-editor/tree/main/app/fonts): font assets · Local font resources used by the UI. · `app/fonts`
- [UI State](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/uiState.tsx): client state · Client-side editor state provider for file selection, workflow data, preview state, and session behavior. · `app/uiState.tsx`
- [Persist State](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/persistState.tsx): client persistence · Session and edit persistence boundary for the browser editor. · `app/persistState.tsx`
- [File Access API](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/types/file-system-access.d.ts): browser typings · Type support for directory-based file workflows via the File System Access API. · `app/types/file-system-access.d.ts`

### Server Boundary

Thin Next.js runtime layer for media fetch and request handling.

- [Media API](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/api/media/route.ts): Next route · Server-side media loading and proxy entry point. · `app/api/media/route.ts`
- [Content Type](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/api/media/detectContentType.ts): detect helper · Content-type detection for fetched media bytes before codec processing. · `app/api/media/detectContentType.ts`

### Codec Library

Binary metadata extraction and re-embedding for supported containers.

- [Dispatcher](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif.ts): codec router · Shared format dispatcher that selects the appropriate embedded-workflow reader/writer. · `app/utils/exif.ts`
- [Binary Utils](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/utils.ts): helpers · Shared low-level byte and parsing helpers used by codecs. · `app/utils/utils.ts`
- [TIFF Encode](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/encodeTIFFBlock.ts): binary builder · Shared block assembly helper for metadata re-encoding. · `app/utils/encodeTIFFBlock.ts`
- [PNG Codec](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-png.ts): container codec · Embedded workflow extraction and write-back for PNG metadata. · `app/utils/exif-png.ts`
- [WEBP Codec](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-webp.ts): container codec · Embedded workflow extraction and write-back for WEBP metadata. · `app/utils/exif-webp.ts`
- [FLAC Codec](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-flac.ts): container codec · Embedded workflow extraction and write-back for FLAC metadata. · `app/utils/exif-flac.ts`
- [MP3 Codec](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-mp3.ts): container codec · Embedded workflow extraction and write-back for MP3 metadata. · `app/utils/exif-mp3.ts`
- [MP4 Codec](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-mp4.ts): container codec · Embedded workflow extraction and write-back for MP4 metadata. · `app/utils/exif-mp4.ts`

### Validation

Unit and fixture-based checks for round-trip correctness.

- [Codec Tests](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/app/utils/exif-png.test.ts): unit tests · Per-format codec tests for parse and round-trip behavior. · `app/utils/exif-png.test.ts`
- [Fixture Media](https://github.com/comfy-org/comfyui-embedded-workflow-editor/tree/main/tests): integration fixtures · Real sample media and workflow sidecars, including malformed WEBP cases. · `tests`

### Tooling

Framework, styling, and CI/runtime configuration.

- [Bun CI](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/.github/workflows/bun-test.yml): workflow · Bun-based test and formatting automation in GitHub Actions. · `.github/workflows/bun-test.yml`
- [Framework Config](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/next.config.ts): next config · Framework-level runtime and build configuration. · `next.config.ts`
- [Middleware](https://github.com/comfy-org/comfyui-embedded-workflow-editor/blob/main/middleware.ts): request middleware · Framework boundary behavior for incoming requests. · `middleware.ts`

## Connections

- Editor → UI State: uses · Editor UI reads and updates browser state.
- Editor → Persist State: persists · Editor session and workflow edits are persisted on the client.
- Editor → File Access API: loads dirs · Editor supports local directory workflows through browser file access.
- Editor → Media API: fetches media · Editor can load remote or proxied media through the server route.
- App Shell → Editor: hosts · App shell renders the main editor page.
- App Shell → Styles: applies · Global stylesheet affects the whole app.
- App Shell → Font Assets: includes · Local font assets are available to the shell.
- Media API → Content Type: detects · Media route uses content-type detection before returning bytes.
- Media API → Dispatcher: feeds · Fetched media is handed to the codec dispatcher after normalization.
- Dispatcher → PNG Codec: routes png · Dispatcher selects the PNG codec for PNG containers.
- Dispatcher → WEBP Codec: routes webp · Dispatcher selects the WEBP codec for WEBP containers.
- Dispatcher → FLAC Codec: routes flac · Dispatcher selects the FLAC codec for FLAC containers.
- Dispatcher → MP3 Codec: routes mp3 · Dispatcher selects the MP3 codec for MP3 containers.
- Dispatcher → MP4 Codec: routes mp4 · Dispatcher selects the MP4 codec for MP4 containers.
- PNG Codec → Binary Utils: uses · PNG codec relies on shared binary helpers.
- WEBP Codec → Binary Utils: uses · WEBP codec relies on shared binary helpers.
- FLAC Codec → TIFF Encode: uses · FLAC codec uses TIFF block assembly helpers for metadata encoding.
- MP3 Codec → Binary Utils: uses · MP3 codec relies on shared binary helpers.
- MP4 Codec → TIFF Encode: uses · MP4 codec uses shared block assembly helpers for metadata encoding.
- PNG Codec → Codec Tests: verified by · PNG codec behavior is covered by unit tests.
- WEBP Codec → Codec Tests: verified by · WEBP codec behavior is covered by unit tests.
- FLAC Codec → Codec Tests: verified by · FLAC codec behavior is covered by unit tests.
- MP3 Codec → Codec Tests: verified by · MP3 codec behavior is covered by unit tests.
- MP4 Codec → Codec Tests: verified by · MP4 codec behavior is covered by unit tests.
- Dispatcher → Fixture Media: validated by · Fixture media exercises real-world round-trip parsing and malformed cases.
- Bun CI → Codec Tests: runs · CI executes codec unit tests.
- Bun CI → Fixture Media: checks · CI relies on fixture media for integration coverage.
- Framework Config → App Shell: configures · Next.js configuration shapes app runtime and build behavior.
- Middleware → Media API: guards · Middleware sits on the request boundary before media handling.
