Skip to content

Commit b46f385

Browse files
christian-byrnechristian-byrne
authored
docs: Update litegraph integration documentation and add ADR (#4771)
1 parent 86509bd commit b46f385

File tree

3 files changed

+157
-1
lines changed

3 files changed

+157
-1
lines changed

‎README.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -524,6 +524,10 @@ Here are some ways to get involved:
524524

525525
Have another idea? Drop into Discord or open an issue, and let's chat!
526526

527+
### Architecture Decision Records
528+
529+
We document significant architectural decisions using ADRs (Architecture Decision Records). See [docs/adr/](docs/adr/) for all ADRs and the template for creating new ones.
530+
527531
## Development
528532

529533
### Prerequisites & Technology Stack
@@ -694,7 +698,15 @@ For detailed instructions on adding and using custom icons, see [src/assets/icon
694698

695699
### litegraph.js
696700

697-
The litegraph library is now included as a git subtree in `src/lib/litegraph`. Any changes to litegraph should be made directly in this location.
701+
Since Aug 5, 2025, litegraph.js is now integrated directly into this repository. It was merged using git subtree to preserve the complete commit history ([PR #4667](https://github.com/Comfy-Org/ComfyUI_frontend/pull/4667), [ADR](docs/adr/0001-merge-litegraph-into-frontend.md)).
702+
703+
#### Important Notes
704+
705+
- **Issue References**: Commits from the original litegraph repository may contain issue/PR numbers (e.g., #4667) that refer to issues/PRs in the original litegraph.js repository, not this one.
706+
- **File Paths**: When viewing historical commits, file paths may show the original structure before the subtree merge. In those cases, just consider the paths relative to the new litegraph folder.
707+
- **Contributing**: All litegraph modifications should now be made directly in this repository.
708+
709+
The original litegraph repository (<https://github.com/Comfy-Org/litegraph.js>) is now archived.
698710

699711
### i18n
700712

‎docs/adr/0001-merge-litegraph-into-frontend.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# 1. Merge LiteGraph.js into ComfyUI Frontend
2+
3+
Date: 2025-08-05
4+
5+
## Status
6+
7+
Accepted
8+
9+
## Context
10+
11+
ComfyUI's frontend architecture currently depends on a forked version of litegraph.js maintained as a separate package (@comfyorg/litegraph). This separation has created several architectural and operational challenges:
12+
13+
**Architectural Issues:**
14+
- The current split creates a distributed monolith where both packages handle rendering, user interactions, and data models without clear separation of responsibilities
15+
- Both frontend and litegraph manipulate the same data structures, forcing tight coupling across the frontend's data model, views, and business logic
16+
- The lack of clear boundaries prevents implementation of modern architectural patterns like MVC or event-sourcing
17+
18+
**Operational Issues:**
19+
- ComfyUI is the only known user of the @comfyorg/litegraph fork
20+
- Managing separate repositories significantly slows developer velocity due to coordination overhead
21+
- Version mismatches between frontend and litegraph cause recurring issues
22+
- No upstream contributions to consider (original litegraph.js is no longer maintained)
23+
24+
**Future Requirements:**
25+
The following planned features are blocked by the current architecture:
26+
- Multiplayer collaboration requiring CRDT-based state management
27+
- Cloud-based backend support
28+
- Alternative rendering backends
29+
- Improved undo/redo system
30+
- Clear API versioning and compatibility layers
31+
32+
## Decision
33+
34+
We will merge litegraph.js directly into the ComfyUI frontend repository using git subtree to preserve the complete commit history.
35+
36+
The merge will:
37+
1. Move litegraph source to `src/lib/litegraph/`
38+
2. Update all import paths from `@comfyorg/litegraph` to `@/lib/litegraph`
39+
3. Remove the npm dependency on `@comfyorg/litegraph`
40+
4. Preserve the full git history using subtree merge
41+
42+
This integration is the first step toward restructuring the application along clear Model-View-Controller boundaries, with state mutations going through a single CRDT-mediated access point.
43+
44+
## Consequences
45+
46+
### Positive
47+
48+
- **Enables architectural refactoring**: Direct integration allows restructuring along proper MVC boundaries
49+
- **Unblocks new features**: Multiplayer, cloud features, and improved undo/redo can now be implemented
50+
- **Faster development**: Eliminates overhead of coordinating changes across two tightly-coupled packages
51+
- **Better developer experience**: No more version mismatch issues or cross-repository debugging
52+
- **Simplified maintenance**: One less repository to maintain, release, and version
53+
54+
### Negative
55+
56+
- **Larger repository**: The frontend repository will increase in size
57+
- **Loss of versioning**: No more semantic versioning for litegraph changes
58+
- **Maintenance responsibility**: Must maintain litegraph code directly
59+
- **Historical references**: Past commit messages may reference issues from the original litegraph repository
60+
61+
## Notes
62+
63+
- Git subtree was chosen over submodules to provide a cleaner developer experience
64+
- The original litegraph repository will be archived after the merge
65+
- Future litegraph improvements will be made directly in the frontend repository

‎docs/adr/README.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Architecture Decision Records
2+
3+
This directory contains Architecture Decision Records (ADRs) for the ComfyUI Frontend project.
4+
5+
## What is an ADR?
6+
7+
An Architecture Decision Record captures an important architectural decision made along with its context and consequences. ADRs help future developers understand why certain decisions were made and provide a historical record of the project's evolution.
8+
9+
## ADR Index
10+
11+
| ADR | Title | Status | Date |
12+
|-----|-------|--------|------|
13+
| [0001](0001-merge-litegraph-into-frontend.md) | Merge LiteGraph.js into ComfyUI Frontend | Accepted | 2025-08-05 |
14+
15+
## Creating a New ADR
16+
17+
1. Copy the template below
18+
2. Name it with the next number in sequence: `NNNN-descriptive-title.md`
19+
3. Fill in all sections
20+
4. Update this index
21+
5. Submit as part of your PR
22+
23+
## ADR Template
24+
25+
```markdown
26+
# N. Title
27+
28+
Date: YYYY-MM-DD
29+
30+
## Status
31+
32+
[Proposed | Accepted | Rejected | Deprecated | Superseded by [ADR-NNNN](NNNN-title.md)]
33+
34+
## Context
35+
36+
Describe the issue that motivated this decision and any context that influences or constrains the decision.
37+
38+
- What is the problem?
39+
- Why does it need to be solved?
40+
- What forces are at play (technical, business, team)?
41+
42+
## Decision
43+
44+
Describe the decision that was made and the key points that led to it.
45+
46+
- What are we going to do?
47+
- How will we do it?
48+
- What alternatives were considered?
49+
50+
## Consequences
51+
52+
### Positive
53+
54+
- What becomes easier or better?
55+
- What opportunities does this create?
56+
57+
### Negative
58+
59+
- What becomes harder or worse?
60+
- What risks are we accepting?
61+
- What technical debt might we incur?
62+
63+
## Notes
64+
65+
Optional section for additional information, references, or clarifications.
66+
```
67+
68+
## ADR Status Values
69+
70+
- **Proposed**: The decision is being discussed
71+
- **Accepted**: The decision has been agreed upon
72+
- **Rejected**: The decision was not accepted
73+
- **Deprecated**: The decision is no longer relevant
74+
- **Superseded**: The decision has been replaced by another ADR
75+
76+
## Further Reading
77+
78+
- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) by Michael Nygard
79+
- [Architecture Decision Records](https://adr.github.io/) - Collection of ADR resources

0 commit comments

Comments
 (0)