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

8.7 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 ⭐ UPDATED

Sequence diagram of what happens during git commit with multi-provider fallback.

Shows:

  • Pre-commit hook execution
  • runner.py orchestration
  • Multi-provider AI fallback (claude → codex → gemini)
  • Patch generation and application
  • Vote processing with marker extraction
  • File staging

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

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 ⭐ UPDATED

Detailed flowchart of AI patch generation and application with provider fallback.

Shows:

  • Prompt building with model hints
  • Multi-provider fallback logic (claude → codex → gemini)
  • Codex JSON parsing
  • 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 provider chain.

5. voting-system.puml ⭐ UPDATED

Voting and promotion logic for multi-stage feature discussions.

Shows:

  • Vote parsing from discussion files
  • Eligible voter calculation
  • Stage-specific promotion thresholds (READY_FOR_DESIGN, READY_FOR_IMPLEMENTATION, etc.)
  • Rejection logic per stage
  • Summary file updates

Best for: Understanding how features move through multi-stage approval (feature → design → implementation → review).

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.

8. ai-provider-fallback.puml 🆕

Detailed flowchart of the multi-provider AI fallback chain with model hints.

Shows:

  • Command chain selection (default, fast, quality)
  • Model hint propagation (TASK COMPLEXITY)
  • Provider-specific execution (Claude CLI, Codex JSON, Gemini)
  • Fallback logic (claude → codex → gemini)
  • Sentinel token handling
  • Error handling per provider

Best for: Understanding how AI provider redundancy works and debugging provider failures.

9. discussion-stages.puml 🆕

State machine diagram showing the complete feature discussion lifecycle through all stages.

Shows:

  • Feature stage (OPEN → READY_FOR_DESIGN)
  • Design stage (OPEN → READY_FOR_IMPLEMENTATION)
  • Implementation stage (IN_PROGRESS → READY_FOR_REVIEW)
  • Review stage (UNDER_REVIEW → APPROVED)
  • Status transitions and promotion conditions
  • Auto-generated files per stage

Best for: Understanding the full feature approval workflow from request to merge.

10. workflow-marker-extraction.puml 🆕

Detailed flowchart of regex-based marker extraction from discussion files.

Shows:

  • Comment parsing from discussion files
  • Regex pattern matching for DECISION, QUESTION, ACTION
  • Support for both plain (DECISION:) and markdown bold (DECISION:) formats
  • Structured data extraction
  • Summary section generation
  • Marker block updates in .sum.md files

Best for: Understanding how structured markers are extracted and why regex was chosen over line-start matching.

Key Concepts Illustrated

Automation Pipeline

Developer commits → Pre-commit hook → runner.py → patcher.py → Multi-Provider AI
                                    → config.py → .ai-rules.yml     (claude → codex → gemini)
                                    → workflow.py → summary.py
                                                     (regex marker extraction)

File Processing (Multi-Stage)

request.md (edited) → AI generates → feature.discussion.md (created/updated)
                                  → feature.discussion.sum.md (updated)
                                  ↓ (votes → READY_FOR_DESIGN)
                                  → design.discussion.md (created)
                                  → design.discussion.sum.md (updated)
                                  ↓ (votes → READY_FOR_IMPLEMENTATION)
                                  → implementation.discussion.md (created)
                                  ↓ (votes → READY_FOR_REVIEW)
                                  → review.discussion.md (created)

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 discussion-stages.puml for complete multi-stage flow
  2. See voting-system.puml for promotion logic per stage
  3. Check file-lifecycle.puml for developer workflow
  4. Review discussion file YAML headers for thresholds

Understanding AI Provider System

  1. See ai-provider-fallback.puml for provider chain logic
  2. Check patcher-pipeline.puml for integration details
  3. Review config/ai.yml for command configuration
  4. Check .git/ai-rules-debug/ for provider outputs

Understanding Marker Extraction

  1. See workflow-marker-extraction.puml for regex patterns
  2. Review automation/workflow.py for implementation
  3. Test with DECISION, QUESTION, ACTION markers in discussions

Implementation Status

Feature Status Diagram
Cascading Rules ✅ Complete cascading-rules.puml
AI Patch Generation ✅ Complete patcher-pipeline.puml
Multi-Provider Fallback ✅ Complete ai-provider-fallback.puml
Model Hints (fast/quality) ✅ Complete ai-provider-fallback.puml
Vote Tracking ✅ Complete voting-system.puml
Multi-Stage Promotion ✅ Complete discussion-stages.puml
Regex Marker Extraction ✅ Complete workflow-marker-extraction.puml
Structured Summaries ✅ Complete workflow-marker-extraction.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)