205 lines
5.5 KiB
Markdown
205 lines
5.5 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**
|
|
**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
|
|
|
|
- **[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)
|