Skip to content

priority-1-features-project-brief.md

Latest commit

 

History

History
408 lines (319 loc) · 10.9 KB

priority-1-features-project-brief.md

File metadata and controls

408 lines (319 loc) · 10.9 KB

Project Brief: PyFlowGraph Priority 1 Features Implementation

Executive Summary

This project implements two critical feature gaps in PyFlowGraph that are considered "table stakes" in the node editor market: a comprehensive Undo/Redo system and Node Grouping/Container functionality. These features directly address the most significant competitive disadvantages identified in market analysis and are essential for PyFlowGraph to be considered a professional-grade tool.

Project Overview

Project Name

PyFlowGraph Feature Parity Initiative - Phase 1

Duration

Estimated 6-8 weeks for full implementation

Priority

Critical - These features are blockers for professional adoption

Impact

  • User Productivity: 40-60% reduction in error recovery time
  • Graph Complexity: Enable 5-10x larger graphs through grouping
  • Market Competitiveness: Move from "interesting prototype" to "viable tool"

Business Context

Problem Statement

PyFlowGraph currently lacks two fundamental features that every professional node editor provides:

  1. No Undo/Redo: Users cannot recover from mistakes without manual reconstruction
  2. No Node Grouping: Complex graphs become unmanageable without abstraction layers

Market Analysis

  • 100% of competitors have both features
  • User feedback consistently cites these as deal-breakers
  • Professional users expect these as baseline functionality

Success Metrics

  • Zero user complaints about missing undo/redo
  • Ability to manage graphs with 200+ nodes effectively
  • 50% reduction in reported user errors
  • Positive user feedback on workflow improvements

Feature 1: Undo/Redo System

Scope Definition

In Scope

  • Multi-level undo/redo (minimum 50 steps)
  • Keyboard shortcuts (Ctrl+Z, Ctrl+Y/Ctrl+Shift+Z)
  • Menu integration with history display
  • Undo/redo for all graph operations:
    • Node creation/deletion
    • Connection creation/deletion
    • Node movement/resizing
    • Property changes
    • Code modifications
    • Copy/paste operations
    • Group/ungroup operations

Out of Scope (Future Phases)

  • Cross-session undo persistence
  • Branching undo trees
  • Undo for file operations

Technical Requirements

Architecture Pattern

Implement Command Pattern with the following structure:

class Command(ABC):
    @abstractmethod
    def execute(self): pass
    
    @abstractmethod
    def undo(self): pass
    
    @abstractmethod
    def get_description(self): str

class CommandHistory:
    def __init__(self, max_size=50):
        self.history = []
        self.current_index = -1
        self.max_size = max_size

Integration Points

  1. node_graph.py: Wrap all graph modifications in commands
  2. node_editor_view.py: Handle keyboard shortcuts
  3. node_editor_window.py: Add menu items and toolbar buttons
  4. node.py: Track property changes
  5. connection.py: Track connection changes

Implementation Approach

Phase 1: Infrastructure (Week 1)

  • Create command base classes
  • Implement CommandHistory manager
  • Add undo/redo stack to NodeGraph

Phase 2: Basic Commands (Week 2)

  • CreateNodeCommand
  • DeleteNodeCommand
  • MoveNodeCommand
  • CreateConnectionCommand
  • DeleteConnectionCommand

Phase 3: Complex Commands (Week 3)

  • CompositeCommand for multi-operations
  • PropertyChangeCommand
  • CodeModificationCommand
  • CopyPasteCommand

Phase 4: UI Integration (Week 4)

  • Keyboard shortcuts
  • Menu items with descriptions
  • Toolbar buttons
  • Visual feedback

User Experience Design

Keyboard Shortcuts

  • Ctrl+Z: Undo last action
  • Ctrl+Y or Ctrl+Shift+Z: Redo
  • Alt+Backspace: Alternative undo (for accessibility)

Menu Structure

Edit Menu
├── Undo [Action Name]  Ctrl+Z
├── Redo [Action Name]  Ctrl+Y
├── ─────────────────────────
├── Undo History...
└── Clear History

Visual Feedback

  • Show action description in status bar
  • Temporary highlight of affected elements
  • Disable undo/redo buttons when not available

Feature 2: Node Grouping/Containers

Scope Definition

In Scope

  • Collapse selected nodes into a single group node
  • Expand groups back to constituent nodes
  • Nested groups (groups within groups)
  • Custom I/O pins for groups
  • Visual representation as single node
  • Save groups as reusable templates
  • Load group templates into any graph

Out of Scope (Future Phases)

  • Cross-project group libraries
  • Online group sharing
  • Auto-grouping suggestions
  • Group versioning

Technical Requirements

Data Model Extensions

class NodeGroup(Node):
    def __init__(self):
        super().__init__()
        self.internal_graph = NodeGraph()
        self.input_mappings = {}  # External pin -> internal node.pin
        self.output_mappings = {} # Internal node.pin -> external pin
        self.collapsed = True
        self.group_color = QColor()
        
class GroupTemplate:
    def __init__(self):
        self.name = ""
        self.description = ""
        self.internal_graph_data = {}
        self.interface_definition = {}

Core Functionality

Group Creation Process:

  1. Select nodes to group
  2. Analyze external connections
  3. Create interface pins automatically
  4. Generate group node
  5. Reroute external connections
  6. Hide internal nodes

Group Expansion Process:

  1. Restore internal nodes to scene
  2. Restore internal connections
  3. Reroute external connections
  4. Remove group node
  5. Maintain positioning

Implementation Approach

Phase 1: Basic Grouping (Week 1-2)

  • Implement NodeGroup class
  • Selection to group conversion
  • Basic collapse/expand
  • Pin interface generation

Phase 2: Visual Representation (Week 3)

  • Custom group node painting
  • Nested view navigation
  • Breadcrumb UI for hierarchy
  • Group color coding

Phase 3: Templates (Week 4)

  • Save group as template
  • Load template system
  • Template management dialog
  • Template metadata

Phase 4: Advanced Features (Week 5)

  • Nested groups support
  • Group property dialog
  • Custom pin configuration
  • Group documentation

User Experience Design

Creation Workflow

  1. Select nodes (Ctrl+Click or drag selection)
  2. Right-click → "Group Selected" or Ctrl+G
  3. Name dialog appears
  4. Group created with auto-generated interface

Interaction Patterns

  • Double-click: Enter/exit group
  • Right-click: Group context menu
  • Alt+Click: Quick expand/collapse
  • Ctrl+Shift+G: Ungroup

Visual Design

Collapsed Group:
┌─────────────────┐
│ 📦 Group Name   │
├─────────────────┤
│ ● Input 1       │
│ ● Input 2       │
│        Output ● │
└─────────────────┘

Expanded View:
Shows internal nodes with breadcrumb:
[Main Graph] > [Group Name] > [Nested Group]

Technical Architecture Impact

File Format Changes

The Markdown flow format needs extension for groups:

## Group: Data Processing
<!--group-metadata
collapsed: true
color: "#4A90E2"
position: [100, 200]
interface:
  inputs: [{name: "data", type: "list"}]
  outputs: [{name: "result", type: "dict"}]
-->

### Internal Nodes
[Internal graph structure here]

## End Group

Performance Considerations

  • Groups reduce scene complexity when collapsed
  • Lazy evaluation of hidden nodes
  • Cache group execution results
  • Memory overhead for group metadata (~1KB per group)

Testing Requirements

Unit Tests

  • Command execution and undo
  • History management
  • Group creation/destruction
  • Template save/load
  • Nested group operations

Integration Tests

  • Undo/redo with groups
  • Copy/paste of groups
  • File save/load with groups
  • Execution of grouped nodes

Performance Tests

  • Undo history with 1000+ operations
  • Groups with 100+ internal nodes
  • Deeply nested groups (10+ levels)

Implementation Risks & Mitigations

Risk 1: Serialization Complexity

Risk: Command serialization for complex operations Mitigation: Start with memory-only undo, add persistence later

Risk 2: Group Execution Order

Risk: Groups may break execution dependency resolution Mitigation: Maintain flat execution graph internally

Risk 3: UI Complexity

Risk: Nested navigation may confuse users Mitigation: Clear breadcrumbs and visual hierarchy

Risk 4: Backward Compatibility

Risk: File format changes break existing graphs Mitigation: Version field in files, migration code

Resource Requirements

Development Team

  • 1 Senior Developer (full-time, 6 weeks)
  • 1 UI/UX Designer (part-time, 2 weeks)
  • 1 QA Tester (part-time, 2 weeks)

Technical Resources

  • Development environment with PyFlowGraph
  • Test dataset of complex graphs
  • Performance profiling tools

Success Criteria

Functional Criteria

  • ✅ 50-step undo history minimum
  • ✅ All graph operations undoable
  • ✅ Groups can be created/expanded
  • ✅ Groups can be nested
  • ✅ Templates can be saved/loaded
  • ✅ Keyboard shortcuts work consistently

Performance Criteria

  • Undo/redo operation < 100ms
  • Group creation < 500ms for 50 nodes
  • No memory leaks in history
  • File size increase < 20% with history

Quality Criteria

  • Zero crashes from undo/redo
  • Consistent state after any undo sequence
  • Groups maintain execution correctness
  • All existing tests still pass

Rollout Strategy

Phase 1: Alpha (Week 5)

  • Internal testing
  • Power user feedback
  • Performance profiling

Phase 2: Beta (Week 6)

  • Public beta release
  • Documentation creation
  • Video tutorials

Phase 3: Release (Week 7-8)

  • Final bug fixes
  • Marketing materials
  • Version 1.0 release

Post-Launch Considerations

Documentation Needs

  • User guide for undo/redo
  • Group creation tutorial
  • Template sharing guide
  • API documentation for developers

Future Enhancements

  • Cloud template library
  • Collaborative undo/redo
  • Smart grouping suggestions
  • Visual undo timeline
  • Group version control

Conclusion

Implementing these Priority 1 features transforms PyFlowGraph from an interesting prototype into a professional tool. The Undo/Redo system provides the safety net users expect, while Node Grouping enables the complexity management required for real-world applications. Together, these features establish feature parity with competitors and create a foundation for future innovation.

Next Steps

  1. Review and approve technical approach
  2. Allocate development resources
  3. Set up development branch
  4. Begin Phase 1 implementation
  5. Schedule weekly progress reviews

Key Decisions Needed

  • Confirm 50-step history limit
  • Approve file format changes
  • Select beta testing group
  • Define template sharing approach

This project brief serves as the definitive guide for implementing PyFlowGraph's Priority 1 features. Success will be measured by user adoption, reduced error rates, and the ability to handle complex professional workflows.