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