nodes/AEmotionStudio-ComfyUI-DiscordSend
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
618b9ae4bb482f6f346ae2dced7a08053f884aac
AEmotionStudio-ComfyUI-Disc…/REFACTOR_PRD.md
T
AEmotionStudioandClaude Opus 4.5 618b9ae4bb docs(prd): update PRD to reflect phases 1-4 completion 
- 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 <noreply@anthropic.com>
2026-01-20 03:22:18 -08:00

14 KiB
Raw Blame History

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)
Reference in New Issue View Git Blame Copy Permalink