274 lines
8.7 KiB
Markdown
274 lines
8.7 KiB
Markdown
# 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](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml)
|
|
2. Open any `.puml` file
|
|
3. Press `Alt+D` to preview
|
|
|
|
### Option 2: Online Viewer
|
|
Visit [PlantUML Web Server](http://www.plantuml.com/plantuml/uml/) and paste the diagram content.
|
|
|
|
### Option 3: Command Line
|
|
```bash
|
|
# 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
|
|
|
|
- **[DESIGN.md](DESIGN.md)** - Complete system design document
|
|
- **[AUTOMATION.md](AUTOMATION.md)** - Automation system details
|
|
- **[automation/README.md](../automation/README.md)** - Quick reference guide
|
|
- **[CLAUDE.md](../CLAUDE.md)** - AI assistant guide for this repo
|
|
|
|
---
|
|
|
|
**Created:** 2025-10-31
|
|
**Last Updated:** 2025-10-31
|
|
**Diagrams:** 7 total (PlantUML format)
|