diff --git a/README.md b/README.md index 32756e810..c919c2e25 100644 --- a/README.md +++ b/README.md @@ -524,6 +524,10 @@ Here are some ways to get involved: Have another idea? Drop into Discord or open an issue, and let's chat! +### Architecture Decision Records + +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. + ## Development ### Prerequisites & Technology Stack @@ -694,7 +698,15 @@ For detailed instructions on adding and using custom icons, see [src/assets/icon ### litegraph.js -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. +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)). + +#### Important Notes + +- **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. +- **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. +- **Contributing**: All litegraph modifications should now be made directly in this repository. + +The original litegraph repository () is now archived. ### i18n diff --git a/docs/adr/0001-merge-litegraph-into-frontend.md b/docs/adr/0001-merge-litegraph-into-frontend.md new file mode 100644 index 000000000..714a7e9dc --- /dev/null +++ b/docs/adr/0001-merge-litegraph-into-frontend.md @@ -0,0 +1,65 @@ +# 1. Merge LiteGraph.js into ComfyUI Frontend + +Date: 2025-08-05 + +## Status + +Accepted + +## Context + +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: + +**Architectural Issues:** +- The current split creates a distributed monolith where both packages handle rendering, user interactions, and data models without clear separation of responsibilities +- Both frontend and litegraph manipulate the same data structures, forcing tight coupling across the frontend's data model, views, and business logic +- The lack of clear boundaries prevents implementation of modern architectural patterns like MVC or event-sourcing + +**Operational Issues:** +- ComfyUI is the only known user of the @comfyorg/litegraph fork +- Managing separate repositories significantly slows developer velocity due to coordination overhead +- Version mismatches between frontend and litegraph cause recurring issues +- No upstream contributions to consider (original litegraph.js is no longer maintained) + +**Future Requirements:** +The following planned features are blocked by the current architecture: +- Multiplayer collaboration requiring CRDT-based state management +- Cloud-based backend support +- Alternative rendering backends +- Improved undo/redo system +- Clear API versioning and compatibility layers + +## Decision + +We will merge litegraph.js directly into the ComfyUI frontend repository using git subtree to preserve the complete commit history. + +The merge will: +1. Move litegraph source to `src/lib/litegraph/` +2. Update all import paths from `@comfyorg/litegraph` to `@/lib/litegraph` +3. Remove the npm dependency on `@comfyorg/litegraph` +4. Preserve the full git history using subtree merge + +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. + +## Consequences + +### Positive + +- **Enables architectural refactoring**: Direct integration allows restructuring along proper MVC boundaries +- **Unblocks new features**: Multiplayer, cloud features, and improved undo/redo can now be implemented +- **Faster development**: Eliminates overhead of coordinating changes across two tightly-coupled packages +- **Better developer experience**: No more version mismatch issues or cross-repository debugging +- **Simplified maintenance**: One less repository to maintain, release, and version + +### Negative + +- **Larger repository**: The frontend repository will increase in size +- **Loss of versioning**: No more semantic versioning for litegraph changes +- **Maintenance responsibility**: Must maintain litegraph code directly +- **Historical references**: Past commit messages may reference issues from the original litegraph repository + +## Notes + +- Git subtree was chosen over submodules to provide a cleaner developer experience +- The original litegraph repository will be archived after the merge +- Future litegraph improvements will be made directly in the frontend repository \ No newline at end of file diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 000000000..67ef529de --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,79 @@ +# Architecture Decision Records + +This directory contains Architecture Decision Records (ADRs) for the ComfyUI Frontend project. + +## What is an ADR? + +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. + +## ADR Index + +| ADR | Title | Status | Date | +|-----|-------|--------|------| +| [0001](0001-merge-litegraph-into-frontend.md) | Merge LiteGraph.js into ComfyUI Frontend | Accepted | 2025-08-05 | + +## Creating a New ADR + +1. Copy the template below +2. Name it with the next number in sequence: `NNNN-descriptive-title.md` +3. Fill in all sections +4. Update this index +5. Submit as part of your PR + +## ADR Template + +```markdown +# N. Title + +Date: YYYY-MM-DD + +## Status + +[Proposed | Accepted | Rejected | Deprecated | Superseded by [ADR-NNNN](NNNN-title.md)] + +## Context + +Describe the issue that motivated this decision and any context that influences or constrains the decision. + +- What is the problem? +- Why does it need to be solved? +- What forces are at play (technical, business, team)? + +## Decision + +Describe the decision that was made and the key points that led to it. + +- What are we going to do? +- How will we do it? +- What alternatives were considered? + +## Consequences + +### Positive + +- What becomes easier or better? +- What opportunities does this create? + +### Negative + +- What becomes harder or worse? +- What risks are we accepting? +- What technical debt might we incur? + +## Notes + +Optional section for additional information, references, or clarifications. +``` + +## ADR Status Values + +- **Proposed**: The decision is being discussed +- **Accepted**: The decision has been agreed upon +- **Rejected**: The decision was not accepted +- **Deprecated**: The decision is no longer relevant +- **Superseded**: The decision has been replaced by another ADR + +## Further Reading + +- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) by Michael Nygard +- [Architecture Decision Records](https://adr.github.io/) - Collection of ADR resources \ No newline at end of file