From 618b9ae4bb482f6f346ae2dced7a08053f884aac Mon Sep 17 00:00:00 2001 From: AEmotionStudio <163354043+AEmotionStudio@users.noreply.github.com> Date: Tue, 20 Jan 2026 03:22:18 -0800 Subject: [PATCH] docs(prd): update PRD to reflect phases 1-4 completion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Mark phases 1-4 as complete with commit references - Add phase 4.1 for PR review bug fixes (5 issues) - Update success metrics with actual line counts: - Image node: 986 → 836 (-15%) - Video node: 1562 → 1092 (-30%) - Total: 2548 → 1928 (-24%) - Utility modules: 6 → 17 - Update change log with all phase completions Co-Authored-By: Claude Opus 4.5 --- REFACTOR_PRD.md | 329 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 329 insertions(+) create mode 100644 REFACTOR_PRD.md diff --git a/REFACTOR_PRD.md b/REFACTOR_PRD.md new file mode 100644 index 0000000..64cf85f --- /dev/null +++ b/REFACTOR_PRD.md @@ -0,0 +1,329 @@ +# ComfyUI-DiscordSend Refactoring PRD + +**Document Type:** Product Requirements Document +**Project:** ComfyUI-DiscordSend Separation of Concerns Refactor +**Version:** 1.0 +**Date:** 2026-01-19 +**Author:** Claude Opus 4.5 + Human Review +**Status:** In Progress (Phases 0-4 Complete) + +--- + +## 1. Overview + +### 1.1 Purpose +This PRD defines the requirements and scope for a comprehensive refactoring of the ComfyUI-DiscordSend project to improve code organization, reduce duplication, and complete missing features. + +### 1.2 Background +The project currently consists of two main components: +- **ComfyUI Nodes**: Production-ready custom nodes for sending images/videos to Discord +- **Discord Bot**: A companion bot for triggering generations from Discord (functional but incomplete) + +### 1.3 Problem Statement +| Issue | Impact | Severity | +|-------|--------|----------| +| 4 critical bugs preventing bot startup | Bot unusable | Critical | +| 1562-line monolithic video node | Hard to maintain/debug | High | +| ~400 lines of duplicated code | Bug fixes needed in multiple places | High | +| Wrong coupling (video imports from image node) | Fragile dependencies | Medium | +| No directory structure for separation | Confusing organization | Medium | +| Incomplete bot features | Missing user functionality | Medium | + +--- + +## 2. Goals & Non-Goals + +### 2.1 Goals +1. **Fix all critical bugs** that prevent the bot from running +2. **Restructure directory layout** with clear separation: `nodes/`, `shared/`, `bot/` +3. **Eliminate code duplication** between image and video nodes +4. **Extract video encoding logic** to reduce video node from 1562 to ~400 lines +5. **Create base node class** for shared functionality +6. **Complete missing bot features**: templates, history, error delivery, WebSocket reconnection +7. **Improve maintainability** through modular design + +### 2.2 Non-Goals +- Adding new node features (beyond bug fixes) +- Changing the Discord webhook API integration +- Modifying ComfyUI compatibility requirements +- Database schema changes (bot uses existing models) +- UI/UX changes to ComfyUI node interface + +--- + +## 3. Requirements + +### 3.1 Functional Requirements + +#### FR-1: Bug Fixes (Phase 0) +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-1.1 | Fix `BotConfig` class name mismatch in `bot/__main__.py` | P0 | +| FR-1.2 | Add missing `json` import to `bot/services/delivery.py` | P0 | +| FR-1.3 | Fix `PermissionLevel` import in `bot/cogs/admin.py` | P0 | +| FR-1.4 | Fix `config.comfyui.url` attribute path in admin cog | P0 | + +#### FR-2: Directory Structure (Phase 1) +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-2.1 | Create `nodes/` directory for node implementations | P1 | +| FR-2.2 | Create `shared/` directory for utilities | P1 | +| FR-2.3 | Create `shared/discord/`, `shared/media/`, `shared/workflow/` subdirectories | P1 | +| FR-2.4 | Move utility files to appropriate locations | P1 | +| FR-2.5 | Update all imports throughout codebase | P1 | +| FR-2.6 | Maintain backward compatibility for ComfyUI node loading | P1 | + +#### FR-3: Shared Utilities (Phase 2) +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-3.1 | Extract filename/timestamp utilities to `shared/filename_utils.py` | P1 | +| FR-3.2 | Extract output directory logic to `shared/path_utils.py` | P1 | +| FR-3.3 | Extract Discord message building to `shared/discord/message_builder.py` | P1 | +| FR-3.4 | Extract CDN URL handling to `shared/discord/cdn_extractor.py` | P1 | + +#### FR-4: Video Encoder Extraction (Phase 3) +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-4.1 | Create `FFmpegEncoder` class in `shared/media/video_encoder.py` | P1 | +| FR-4.2 | Create `PILGifEncoder` fallback class | P1 | +| FR-4.3 | Extract format detection to `shared/media/format_utils.py` | P1 | +| FR-4.4 | Reduce video node to orchestration layer (~400 lines) | P1 | + +#### FR-5: Base Node Class (Phase 4) +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-5.1 | Create `BaseDiscordNode` class in `nodes/base_node.py` | P2 | +| FR-5.2 | Extract common `INPUT_TYPES` definitions | P2 | +| FR-5.3 | Extract shared methods (sanitize, send, etc.) | P2 | +| FR-5.4 | Refactor image and video nodes to inherit from base | P2 | + +#### FR-6: Bot Features (Phase 5) +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-6.1 | Implement WebSocket reconnection with exponential backoff | P1 | +| FR-6.2 | Implement error delivery to Discord users | P1 | +| FR-6.3 | Implement `/template` commands (save, load, list, delete) | P2 | +| FR-6.4 | Implement `/history` and `/rerun` commands | P2 | +| FR-6.5 | Create `config.yaml.example` template | P1 | +| FR-6.6 | Create `.env.example` template | P1 | + +### 3.2 Non-Functional Requirements + +| ID | Requirement | Metric | +|----|-------------|--------| +| NFR-1 | Reduce total node code by >50% | 2548 → <1200 lines | +| NFR-2 | Eliminate code duplication | ~400 lines → 0 | +| NFR-3 | Maintain test pass rate | All existing tests pass | +| NFR-4 | No breaking changes to ComfyUI | Nodes load and function identically | +| NFR-5 | Improve modularity | 12+ separate utility modules | + +--- + +## 4. Architecture + +### 4.1 Current State +``` +comfyui-discordsend/ +├── discord_image_node.py (986 lines) +├── discord_video_node.py (1562 lines) +├── discordsend_utils/ (6 files, tightly coupled) +└── bot/ (incomplete, 4 bugs) +``` + +### 4.2 Target State +``` +comfyui-discordsend/ +├── __init__.py # ComfyUI entry point +├── nodes/ # Node implementations (~950 lines total) +│ ├── __init__.py +│ ├── base_node.py # Shared base class +│ ├── image_node.py # Image-specific logic +│ └── video_node.py # Video-specific logic +├── shared/ # Shared utilities (12 modules) +│ ├── discord/ # Discord integration +│ │ ├── webhook_client.py +│ │ ├── message_builder.py +│ │ └── cdn_extractor.py +│ ├── media/ # Media processing +│ │ ├── image_processing.py +│ │ ├── video_encoder.py +│ │ └── format_utils.py +│ ├── workflow/ # Workflow utilities +│ │ ├── sanitizer.py +│ │ ├── prompt_extractor.py +│ │ └── workflow_builder.py +│ ├── github_integration.py +│ ├── filename_utils.py +│ ├── path_utils.py +│ └── logging_config.py +└── bot/ # Fully functional bot + ├── cogs/ + │ ├── generate.py + │ ├── queue.py + │ ├── admin.py + │ ├── templates.py # NEW + │ └── history.py # NEW + └── ... +``` + +### 4.3 Component Dependencies + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ComfyUI Runtime │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ ImageNode │ │ VideoNode │ │ +│ └──────┬───────┘ └──────┬───────┘ │ +│ │ │ │ +│ └────────┬───────────┘ │ +│ ▼ │ +│ ┌──────────────┐ │ +│ │ BaseNode │ │ +│ └──────┬───────┘ │ +└────────────────┼────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ shared/ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ discord │ │ media │ │workflow │ │ utils │ │ +│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ (logging_config only) +┌─────────────────────────────────────────────────────────────────┐ +│ bot/ │ +│ (Minimal shared dependency - mostly independent) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 5. Phased Implementation + +### Phase 0: Critical Bug Fixes ✅ COMPLETE +- Fix 4 bugs preventing bot startup +- Verify all existing tests pass +- **Status:** Complete (2026-01-19) + +### Phase 1: Directory Restructure ✅ COMPLETE +- Create new directory structure (`nodes/`, `shared/`) +- Move files to new locations +- Update all imports +- Remove deprecated `discordsend_utils/` +- **Status:** Complete (2026-01-20) +- **Commit:** 852840d + +### Phase 2: Extract Shared Utilities ✅ COMPLETE +- Create `filename_utils.py` - filename with date/time/dimensions +- Create `path_utils.py` - output directory handling +- Create `message_builder.py` - Discord message construction +- Create `cdn_extractor.py` - CDN URL extraction and file sending +- **Status:** Complete (2026-01-20) +- **Commit:** a208cd4 +- **Result:** 522 lines removed from nodes (image: -161, video: -361) + +### Phase 3: Extract Video Encoder ✅ COMPLETE +- Create `FFmpegEncoder` class with format-specific encoding +- Create `PILEncoder` class for GIF/WebP fallback +- Create `format_utils.py` - format detection, validation, Discord compatibility +- Refactor video node to use shared encoders +- **Status:** Complete (2026-01-20) +- **Commit:** 76da850 +- **Result:** Video node reduced from 1562 to 1092 lines (-470 lines, 30% reduction) + +### Phase 4: Create Base Node Class ✅ COMPLETE +- Create `BaseDiscordNode` (343 lines) in `nodes/base_node.py` +- Extract common `INPUT_TYPES` generators (Discord, CDN, filename metadata) +- Extract shared methods (sanitize, send, GitHub update, etc.) +- **Status:** Complete (2026-01-20) +- **Commit:** 87c97e0 +- **Note:** Nodes not yet refactored to inherit from base (deferred to reduce risk) + +### Phase 4.1: PR Review Bug Fixes ✅ COMPLETE +- Fix else block indentation in batch Discord send (1e94a69) +- Add section header when only dimensions displayed (b8aadd7) +- Restore SDXL workflow prompt extraction support (36c5d06) +- Prevent redundant CDN URL sends on 204 responses (cc07d20) +- Add trailing newline to metadata section formatting (0d6ed9d) +- **Status:** Complete (2026-01-20) + +### Phase 5: Complete Bot Features +- WebSocket reconnection +- Error delivery +- Templates cog +- History cog +- Config templates +- **Deliverable:** Fully functional bot + +### Phase 6: Final Cleanup +- Update documentation +- Add new tests +- Remove dead code +- **Deliverable:** Production-ready codebase + +--- + +## 6. Success Metrics + +| Metric | Original | Current | Target | Status | +|--------|----------|---------|--------|--------| +| Image node lines | 986 | 836 | ~350 | 🟡 -150 lines (15%) | +| Video node lines | 1562 | 1092 | ~400 | 🟡 -470 lines (30%) | +| Total node lines | 2548 | 1928 | ~750 | 🟡 -620 lines (24%) | +| Base node class | 0 | 343 | ~200 | ✅ Created | +| Utility modules | 6 | 17 | 12+ | ✅ Exceeded | +| Code duplication | ~400 lines | ~200 | 0 | 🟡 In progress | +| Test pass rate | 46/52 | 46/52 | 52/52 | 🟡 Maintained | +| Bot features | 60% | 60% | 100% | ⬜ Phase 5 | + +**Notes:** +- Node line counts don't include base_node.py (343 lines of reusable code) +- 6 test failures are pre-existing numpy mocking issues, not refactoring-related +- Nodes have not yet been refactored to inherit from BaseDiscordNode + +--- + +## 7. Risks & Mitigations + +| Risk | Likelihood | Impact | Mitigation | +|------|------------|--------|------------| +| Breaking ComfyUI node loading | Medium | High | Test after each phase; maintain `__init__.py` | +| Breaking existing workflows | Low | High | Preserve node class names exactly | +| Introducing new bugs | Medium | Medium | Comprehensive tests; review after each phase | +| Merge conflicts | Low | Low | Work on feature branch; small commits | +| Scope creep | Medium | Medium | Strict adherence to PRD; defer new features | + +--- + +## 8. Out of Scope (Future Work) + +- New node types (audio, 3D, etc.) +- Multi-webhook support per node +- Cloud storage integration (S3, GCS) +- Web dashboard for bot +- Rate limiting per user in nodes +- Encrypted webhook storage + +--- + +## 9. Approval & Sign-off + +| Role | Name | Date | Status | +|------|------|------|--------| +| Developer | Claude Opus 4.5 | 2026-01-19 | Approved | +| Reviewer | Human | 2026-01-19 | Approved | + +--- + +## 10. Change Log + +| Version | Date | Author | Changes | +|---------|------|--------|---------| +| 1.0 | 2026-01-19 | Claude | Initial PRD created | +| 1.0.1 | 2026-01-19 | Claude | Phase 0 marked complete | +| 1.1 | 2026-01-20 | Claude | Phase 1 complete - directory restructure | +| 1.2 | 2026-01-20 | Claude | Phase 2 complete - shared utilities extracted | +| 1.3 | 2026-01-20 | Claude | Phase 3 complete - video encoder extraction | +| 1.4 | 2026-01-20 | Claude | Phase 4 complete - BaseDiscordNode created | +| 1.4.1 | 2026-01-20 | Claude | Phase 4.1 - PR review bug fixes (5 issues resolved) |