# Crackerjack Architecture Diagrams

This directory contains visual documentation for the Crackerjack project, designed to help both humans and AI agents quickly understand the system architecture.

## Diagram Index

### Core Architecture

| Diagram | Description | Used In |
|---------|-------------|---------|
| [oneiric-workflow-dag.png](./oneiric-workflow-dag.png) | Complete execution pipeline from CLI entry through all phases: Fast Hooks → Code Cleaning → Comprehensive Hooks → Tests → AI Batch Fixing | [README.md](../../README.md) |
| [layered-architecture.png](./layered-architecture.png) | 8-layer modular architecture with 100% protocol compliance: Entry → CLI → Coordinators → Managers → Services → Adapters → Agents → MCP | [CLAUDE.md](../../CLAUDE.md) |

### AI & Agent System

| Diagram | Description | Used In |
|---------|-------------|---------|
| [ai-agent-orchestration.png](./ai-agent-orchestration.png) | 12 specialized AI agents with confidence-based routing, issue classification, and batch processing loop | [README.md](../../README.md) |
| [agent-selection.png](./agent-selection.png) | Decision tree for routing tasks to appropriate specialized agents by domain (language, database, infrastructure, testing, security, architecture) | [CLAUDE.md](../../CLAUDE.md) |

### Quality & Decision Frameworks

| Diagram | Description | Used In |
|---------|-------------|---------|
| [decision-framework.png](./decision-framework.png) | "Fix Now or Later?" decision tree: Blocker → While-Here → Critical → Defer with examples for each category | [CLAUDE.md](../../CLAUDE.md) |
| [quality-hooks.png](./quality-hooks.png) | Fast hooks (~5s) vs Comprehensive hooks (~30s) execution flow with retry logic and AI-fix integration | [README.md](../../README.md) |

### Security & Validation

| Diagram | Description | Used In |
|---------|-------------|---------|
| [security-threat-model.png](./security-threat-model.png) | 6 attack vectors (Command Injection, Path Traversal, DoS, Race Conditions, Input Validation, Privilege Escalation) mapped to defense mechanisms and security layers | [SECURITY.md](../reference/SECURITY.md) |
| [pattern-management.png](./pattern-management.png) | Centralized regex pattern registry with validation pipeline: Size limits → Iteration limits → Timeout guards → Thread-safe caching | [README.md](../../README.md) |

### Adapters & Tools

| Diagram | Description | Used In |
|---------|-------------|---------|
| [adapter-taxonomy.png](./adapter-taxonomy.png) | 18 QA adapters organized by category (AI, Complexity, Format, Lint, LSP, Refactor, Security, Type, Utility) with protocol-based registration | [README.md](../../README.md) |

## Quick Reference

### By Priority (Impact on Understanding)

1. **Start Here**: `oneiric-workflow-dag.png` - Understand the complete execution flow
1. **Architecture**: `layered-architecture.png` - Understand the codebase structure
1. **AI System**: `ai-agent-orchestration.png` - Understand how AI fixing works
1. **Quality**: `quality-hooks.png` - Understand the two-phase quality system
1. **Decision Making**: `decision-framework.png` - Know when to fix vs defer

### By Audience

**New Contributors:**

- `layered-architecture.png` - Where does my code go?
- `oneiric-workflow-dag.png` - How does everything connect?
- `adapter-taxonomy.png` - What tools are available?

**AI Agents (Claude, etc.):**

- `agent-selection.png` - Which specialist to use?
- `ai-agent-orchestration.png` - How does batch fixing work?
- `decision-framework.png` - Fix now or later?

**Security Reviewers:**

- `security-threat-model.png` - What threats are mitigated?
- `pattern-management.png` - How is regex handled safely?

## Generation Details

These diagrams were generated using the **Mermaid MCP server** with the following characteristics:

- **Format**: PNG (for universal compatibility)
- **Theme**: Default Mermaid theme
- **Tool**: `mcp__mermaid__generate_mermaid_diagram`
- **Total Size**: ~673 KB

## Updating Diagrams

To regenerate or modify diagrams:

1. Use the Mermaid MCP server via Claude Code
1. Modify the Mermaid syntax as needed
1. Save output to this directory with descriptive filename
1. Update this README with any new diagrams
1. Embed in appropriate documentation files

## Mermaid Source

The Mermaid source code for each diagram can be regenerated by examining the diagram and reconstructing the flowchart syntax. For complex diagrams, consider storing `.mmd` source files alongside PNGs for easier maintenance.
