rob
/
CascadingDev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
CascadingDev/docs/diagrams-README.md

5.5 KiB
Raw Blame History

CascadingDev Architecture Diagrams

This directory contains PlantUML diagrams documenting the CascadingDev automation system.

Viewing the Diagrams

Option 1: VS Code (Recommended)

  1. Install the PlantUML extension
  2. Open any .puml file
  3. Press Alt+D to preview

Option 2: Online Viewer

Visit PlantUML Web Server and paste the diagram content.

Option 3: Command Line

# Install PlantUML
sudo apt install plantuml  # or brew install plantuml

# Generate PNG
plantuml docs/architecture-overview.puml

# Generate SVG (better quality)
plantuml -tsvg docs/*.puml

Diagram Index

1. architecture-overview.puml

High-level system architecture showing how all components interact.

Shows:

  • User project structure
  • Automation modules (runner, config, patcher, workflow)
  • AI provider integration
  • Data flow from developer to commit

Best for: Understanding the big picture and component relationships.

2. commit-workflow.puml

Sequence diagram of what happens during git commit.

Shows:

  • Pre-commit hook execution
  • runner.py orchestration
  • AI API calls
  • Patch generation and application
  • Vote processing
  • File staging

Best for: Understanding the complete commit-time automation flow.

3. cascading-rules.puml

Configuration system showing how .ai-rules.yml files cascade and merge.

Shows:

  • Rule file locations (root, features/, FR_*/
  • Merge precedence (nearest wins)
  • File associations
  • Rule definitions

Best for: Understanding how to configure automation rules.

4. patcher-pipeline.puml

Detailed flowchart of AI patch generation and application.

Shows:

  • Prompt building
  • AI command execution
  • Patch extraction (with markers)
  • Patch sanitization
  • git apply strategies (strict → 3-way → fallback)
  • Debug artifact saving
  • Error handling

Best for: Debugging patch application issues or understanding the AI integration.

5. voting-system.puml

Voting and promotion logic for feature discussions.

Shows:

  • Vote parsing from discussion files
  • Eligible voter calculation
  • Promotion thresholds (READY_FOR_IMPLEMENTATION)
  • Rejection logic
  • Summary file updates

Best for: Understanding how features move through approval stages.

6. file-lifecycle.puml

Activity diagram showing the complete lifecycle of a feature request.

Shows:

  • From request.md creation to implementation
  • AI-generated file creation
  • Vote-driven status transitions
  • Implementation gate triggering
  • Which files to edit vs. auto-generated

Best for: Understanding the developer workflow and when automation triggers.

7. directory-structure.puml

Component diagram showing the project structure.

Shows:

  • CascadingDev repository layout
  • Install bundle structure
  • User project structure after setup
  • Debug artifact locations
  • File relationships

Best for: Navigating the codebase and understanding where files live.

Key Concepts Illustrated

Automation Pipeline

Developer commits → Pre-commit hook → runner.py → patcher.py → Claude API
                                    → config.py → .ai-rules.yml
                                    → workflow.py → summary.py

File Processing

request.md (edited) → AI generates → feature.discussion.md (created/updated)
                                  → feature.discussion.sum.md (updated)
                                  → implementation.discussion.md (gated)

Voting Flow

Participant comments → VOTE: lines parsed → Count eligible votes
                                         → Check thresholds
                                         → Update status
                                         → Generate implementation (if ready)

Error Handling

API overload → Log error → Continue with other files → Commit succeeds
Patch fails → Save debug artifacts → Log error → Continue

Common Workflows

Adding a New Rule

  1. See cascading-rules.puml for rule structure
  2. Edit Docs/features/.ai-rules.yml
  3. Add file_associations and rules sections
  4. Commit and test

Debugging Automation

  1. Check .git/ai-rules-debug/*.raw.out for AI responses
  2. See patcher-pipeline.puml for patch processing steps
  3. Review commit-workflow.puml for execution order

Understanding Status Transitions

  1. See voting-system.puml for promotion logic
  2. Check file-lifecycle.puml for state machine
  3. Review discussion file YAML headers for thresholds

Implementation Status

Feature Status Diagram
Cascading Rules ✅ Complete cascading-rules.puml
AI Patch Generation ✅ Complete patcher-pipeline.puml
Vote Tracking ✅ Complete voting-system.puml
Promotion Logic ✅ Complete voting-system.puml
Implementation Gate ✅ Complete file-lifecycle.puml
Error Handling ✅ Complete commit-workflow.puml

Related Documentation

Created: 2025-10-31 Last Updated: 2025-10-31 Diagrams: 7 total (PlantUML format)