mirror of
https://github.com/Comfy-Org/ComfyUI_frontend.git
synced 2026-07-03 21:58:32 +00:00
be38f14619
## Summary Realign the ECS architecture docs and ADR 0008 with the shipped direction (PR #12617): entity data lives in dedicated Pinia stores keyed by string IDs, rather than one unified \"World\" registry addressed by branded entity IDs. ## Changes - **What**: Docs-only. Retarget the `docs/architecture/` set + ADR 0008 + agent guidance from the single-World/branded-`*EntityId` model to the dedicated-store model that PR #12617 actually shipped (`widgetValueStore` keyed by `WidgetId`, `layoutStore`, `nodeOutputStore`, `domWidgetStore`, `subgraphNavigationStore`, `previewExposureStore`). - `AGENTS.md` + `.agents/checks/adr-compliance.md`: point entity-data guidance at dedicated stores; fix the inverted `world.getComponent` compliance check (it flagged correct store-based code). - `ADR 0008`: dated amendment note (stays Proposed); rewrite the World section → dedicated stores, Branded ID design (`WidgetId` composite string), migration strategy, render-loop, consequences, notes. - `proto-ecs-stores.md`: flip the \"Unified World / branded IDs\" framing from gap-to-close → target; replace the deleted `PromotedWidgetViewManager` with the `input.widgetId` store-backed model; fix key formats and store count. - `ecs-target-architecture.md` / `ecs-lifecycle-scenarios.md` / `ecs-migration-plan.md`: reframe all `world.*` APIs and `*EntityId` brands to per-store APIs + string keys; mark already-shipped migration phases done. - `subgraph-boundaries-and-promotion.md` / `entity-interactions.md` / `entity-problems.md`: scope-tagged store entries; swap removed `PromotionStore` for `previewExposureStore`. - `appendix-critical-analysis.md`: post-pivot status banner + resolution notes on the critiques the pivot vindicated; still-open gaps (extension callbacks, atomicity, Y.js↔ECS) left live. - `appendix-ecs-pattern-survey.md`: supersede banner; keep the external library survey (§1). - Delete obsolete `ecs-world-command-api.md` (its command-pattern argument folded into ADR 0008). - **Breaking**: None (documentation only). ## Review Focus - ADR 0008 stays **Proposed** with an amendment note rather than a new superseding ADR — confirm that's the preferred mechanism vs. a fresh ADR. - Numeric per-kind brands (`NodeEntityId`, `LinkEntityId`, …) are retained in ADR 0008 but explicitly marked aspirational/unshipped; only `WidgetId` (composite string) reflects shipped code. - `appendix-ecs-pattern-survey.md` §2–§4 are kept under a supersede banner as historical record (they describe the deleted `src/world/` substrate) rather than rewritten — confirm that's preferred over deletion. - Net −384 lines; no code or test changes. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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 | Merge LiteGraph.js into ComfyUI Frontend | Accepted | 2025-08-05 |
| 0002 | Restructure as a Monorepo | Accepted | 2025-08-25 |
| 0003 | Centralized Layout Management with CRDT | Proposed | 2025-08-27 |
| 0004 | Fork PrimeVue UI Library | Rejected | 2025-08-27 |
| 0005 | Remove Import Map for Vue Extensions | Accepted | 2025-12-13 |
| 0006 | PrimitiveNode Copy/Paste Lifecycle | Proposed | 2026-02-22 |
| 0007 | NodeExecutionOutput Passthrough Schema | Accepted | 2026-03-11 |
| 0008 | Entity Component System | Proposed | 2026-03-23 |
| 0009 | Subgraph Promoted Widgets Use Linked Inputs | Proposed | 2026-05-05 |
| 0010 | Remove Nx Orchestration | Accepted | 2026-05-19 |
Creating a New ADR
- Copy the template below
- Name it with the next number in sequence:
NNNN-descriptive-title.md - Fill in all sections
- Update this index
- Submit as part of your PR
ADR Template
# 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 by Michael Nygard
- Architecture Decision Records - Collection of ADR resources