# 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)