2nd/10_Wiki/Topics/Comfyui/Workflow.json (Frontend Format).md

---
id: workflow.json-(frontend-format)
title: "Workflow.json (Frontend Format)"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["Frontend JSON", "Full Workflow Export"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.85
created_at: 2026-05-19
updated_at: 2026-05-19
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법"]
raw_sources: ["NotebookLM Synthesis"]
applied_in: ["comfyui-workflow-to-api-converter-endpoint", "ComfyUI-to-Python-Extension", "ComfyUI-WorkflowGenerator"]
github_commit: ""
---

# [[Workflow.json (Frontend Format)]]

## 🎯 한 줄 통찰 (One-line insight)
ComfyUI의 시각적 편집 상태와 노드 간의 논리적 연결을 **Litegraph 표준**에 따라 완벽하게 보존하여, 인간의 재편집과 기계적 실행 사이의 가교 역할을 수행하는 전제 상태(Full State) 스냅샷 [1, 2].

## 🧠 핵심 개념 (Core concepts)
1.  **Litegraph 표준 준수:** ComfyUI 웹 인터페이스의 캔버스 레이아웃을 정의하는 라이브러리인 Litegraph 형식을 따르며, 시각적 렌더링에 필요한 모든 데이터를 포함한다 [1, 2].
2.  **시각적 메타데이터(Visual Metadata):** 노드의 좌표(pos), 크기(size), 그룹 구성, 색상, 노드의 축소(collapsed) 또는 고정(pinned) 상태 등의 정보를 상세히 기록한다 [1, 3, 4].
3.  **명시적 링크 구조(Explicit Links):** 노드 간의 연결을 별도의 `links` 배열 내에서 고유 ID를 가진 명시적 객체로 관리하여 그래프의 시각적 연결성을 유지한다 [2, 3, 5].
4.  **노드 식별자(Node Identification):** 각 노드는 주로 숫자 형태의 고유 문자열 ID(예: "1", "2")로 식별되며, 이는 그래프 탐색 및 UI 렌더링의 기준이 된다 [1, 2, 6].

## 🧩 추출된 패턴 (Extracted patterns)
-   **Full UI Export 패턴:** 단순히 실행 로직만 저장하는 것이 아니라, 사용자가 작업하던 환경을 그대로 복구할 수 있도록 캔버스의 모든 상태를 캡처하는 방식이다 [7, 8].
-   **Metadata Embedding 패턴:** 생성된 PNG 이미지의 `tEXt` 또는 `zTXt` 청크에 Frontend JSON 데이터를 주입하여 이미지 자체가 워크플로우 백업 파일 역할을 하도록 설계되었다 [9-11].
-   **역방향 실행 모델(Execution Model Inversion):** JSON 내에 수많은 노드가 존재하더라도 실행 엔진은 출력 노드(Save Image 등)부터 역추적하여 필요한 노드만 실행하며, 사용되지 않는 노드는 성능에 영향을 주지 않고 보존된다 [12].

## 📖 세부 내용 (Details)
Frontend Format인 `workflow.json`은 ComfyUI의 기본 저장 형식으로, 사용자가 웹 인터페이스에서 워크플로우를 저장하거나 공유할 때 주로 사용된다 [1, 2, 13]. 

### 1. 주요 데이터 구조
-   **nodes:** 워크플로우를 구성하는 개별 노드들의 배열이다. 각 노드 객체는 클래스 타입(`type`), 좌표(`pos`), 크기(`size`), 실행 순서(`order`), 모드(`mode`, 활성/우회 등), 그리고 위젯 설정값(`widgets_values`)을 포함한다 [4, 14].
-   **links:** 노드 사이의 와이어(Wire) 연결을 정의하는 최상위 배열이다. 각 링크는 보통 6개의 요소를 가진 배열이나 객체 형태로, 소스 노드 ID, 소스 슬롯, 타겟 노드 ID, 타겟 슬롯 정보를 담고 있다 [5].
-   **groups:** 캔버스 상에서 노드들을 논리적으로 묶어주는 시각적 그룹 정보를 저장한다 [4].

### 2. API Format(Backend)과의 차이점
Frontend Format은 사용자 인터페이스 정보를 모두 포함하기 때문에 파일 크기가 상대적으로 크며, 백엔드 실행 엔진이 직접 해석하기에는 부적절한 구조를 가지고 있다 [1, 3, 15]. 반면 API Format은 UI 메타데이터를 제거하고 노드 입력 내에 링크 정보를 직접 임베딩하여 실행 최적화에 집중한다 [1, 16, 17].

### 3. 상호 운용성 및 한계
-   **이미지 기반 로딩:** PNG 이미지에 포함된 메타데이터를 통해 워크플로우를 즉시 복구할 수 있으나, 이미지 편집기나 소셜 미디어 플랫폼을 거치면서 메타데이터가 손실될 위험이 있다 [9, 11, 18].
-   **버전 호환성:** ComfyUI는 지속적으로 업데이트되므로, 구버전의 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있다 [18].
-   **종속성 문제:** JSON 파일 자체에는 모델 가중치나 커스텀 노드의 코드가 포함되지 않으므로, 로컬 환경에 해당 노드나 모델이 없을 경우 'Red Box' 오류가 발생한다 [19, 20].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
-   **파일 확장자 혼용:** 소스에 따라 API 전용 포맷을 `workflow_api.json`으로, 프론트엔드 포맷을 `workflow.json`으로 명확히 구분하기도 하지만, 일반적인 대화에서는 모두 '워크플로우 JSON'으로 통칭되기도 한다 [1, 21].
-   **메타데이터 취약성:** PNG에 임베딩된 JSON은 압축 소프트웨어나 네트워크 전송 시 소실될 수 있다는 점이 지속적으로 지적된다 [11, 18].

## 🛠️ 적용 사례 (Applied in summary)
-   **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 측의 자바스크립트 로직을 파이썬으로 변환하여, 프론트엔드 형식의 JSON을 API 형식으로 서버 사이드에서 변환하는 기능을 제공한다 (커밋 bc85382 참조) [15, 22, 23].
-   **ComfyUI-to-Python-Extension:** 프론트엔드 워크플로우 메타데이터를 포함한 스크립트를 생성하여, 저장된 이미지에서 워크플로우를 재임포트할 수 있도록 지원한다 [24, 25].
-   **ComfyUI-WorkflowGenerator:** LLM을 통해 생성된 논리적 구조를 최종적으로 실행 가능한 Frontend JSON 또는 API JSON 포맷으로 빌드하는 `WorkflowBuilder` 노드를 포함한다 [26, 27].

## ✅ 검증 상태 및 신뢰도
-   **상태:** draft
-   **검증 단계:** conceptual (공식 문서 및 다수의 오픈소스 프로젝트에서 핵심 규격으로 사용됨)
-   **출처 신뢰도:** B (공식 문서 및 기술 블로그, GitHub 리포지토리를 통한 교차 검증 완료)
-   **중복 검사 결과:** 신규 생성

## 🔗 관련 문서 링크 (Related document links)

### 상위/유사 개념
#### [아키텍처/기반 기술]
- [[Litegraph Standard]]
  - 연결 이유: Frontend JSON 포맷의 구조적 근간이 되는 라이브러리 규격임 [1].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 배치 및 링크 렌더링 원리.
- [[Workflow.api.json (Backend Format)]]
  - 연결 이유: Frontend JSON에서 UI 정보를 제거하고 실행 효율성을 극대화한 대응 포맷임 [1, 3].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각적 표현과 논리적 실행 구조의 분리.

#### [구현/활용 도구]
- [[ComfyUI Manager]]
  - 연결 이유: JSON 내의 `class_type`을 분석하여 누락된 커스텀 노드를 설치해주는 필수 관리 도구임 [20].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 종속성 관리 및 환경 복구 프로세스.
- [[Workflow Extractor]]
  - 연결 이유: 이미지 메타데이터에 숨겨진 Frontend JSON을 추출하는 전문 도구임 [28, 29].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 메타데이터 보존 및 데이터 복구 기술.

### 심층 후속 질문 (Deeper Research Questions)
- Frontend JSON의 `order` 필드가 실제 백엔드의 실행 순서와 항상 일치하는가? [14]
- PNG 이미지의 `tEXt` 청크와 `zTXt` 청크 중 어느 방식이 워크플로우 데이터 저장에 더 유리한가? [11]
- `comfyui-workflow-to-api-converter-endpoint`는 서브그래프(Subgraph)가 포함된 복잡한 프론트엔드 JSON을 어떻게 처리하는가? [23, 30]
- 노드 ID가 문자열로 저장될 때와 숫자로 저장될 때의 시스템 처리 차이는 무엇인가? [4, 6]
- 모델 해싱(Model Hashing) 기술이 JSON의 포터빌리티(Portability) 문제를 어떻게 해결하는가? [31]
- LLM이 생성한 논리적 다이어그램을 표준 V1.0 스키마에 맞게 검증하는 구체적인 메커니즘은 무엇인가? [26, 32]

### 실무 적용 맥락 (Practical Application Contexts)
- **Implementation:** 커스텀 앱에서 워크플로우를 로드할 때, 우선 Frontend 포맷으로 불러와 사용자에게 시각적으로 보여준 뒤 실행 시점에만 API 포맷으로 변환하여 요청한다 [33].
- **System Design:** 버전 관리 시스템(Git)에 워크플로우를 저장할 때, 시각적 변경 사항을 추적하기 위해 Frontend 포맷을 유지하는 것이 유리하다 [34].
- **Operation / Maintenance:** 사용자가 공유한 이미지에서 워크플로우를 복원할 수 없는 경우, `exiftool` 등을 사용해 메타데이터 존재 여부를 선제적으로 확인한다 [29, 35].
- **Learning Path:** 초보자는 시각적 노드 연결 방식을 통해 논리 구조를 익히고, 숙련자는 JSON의 `widgets_values`를 직접 수정하여 자동화 스크립트를 작성한다 [13, 36].

### 인접 주변 주제 (Adjacent Topics)
- [[Custom Nodes]]
  - 확장 방향: JSON 내의 `type` 필드가 실제 파이썬 클래스와 매핑되는 방식 연구.
- [[JSON Schema v1.0]]
  - 확장 방향: 워크플로우 파일의 구조적 무결성을 검증하는 기술적 명세 확인 [14].

## 📝 변경 이력 (Change history)
- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine based on 18 sources.