project-diagrams

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: project-diagrams
description: "Create publication-quality architecture diagrams using Nano Banana Pro AI or Mermaid. Specialized in system architecture, C4 diagrams, data flow, sequence diagrams, and software design visualizations for project planning."
allowed-tools: [Read, Write, Edit, Bash]
---

# Project Diagrams and Architecture Visualizations

## Overview

Project diagrams transform complex software architectures and system designs into clear visual representations. **This skill offers two diagram generation approaches:**

| Approach | Best For | Output |
|----------|----------|--------|
| **Nano Banana Pro AI** | Publication-quality visuals, presentations, complex custom diagrams | PNG images |
| **Mermaid** | Version-controlled docs, GitHub markdown, editable diagrams | SVG/PNG from code |

## Choosing Your Approach

### Use Nano Banana Pro AI when:
- You need visually polished, publication-ready diagrams
- Creating custom visualizations that don't fit standard templates
- Diagrams for presentations, proposals, or client deliverables
- Complex architectural diagrams with custom styling

### Use Mermaid when:
- Diagrams need to be version-controlled in git (text diffs)
- Embedding directly in GitHub/GitLab markdown
- You need to edit and iterate quickly on diagram structure
- Standardized diagram types (flowcharts, sequence, C4, ERD, Gantt)
- Collaborative documentation where others may edit

---

## Option 1: Nano Banana Pro AI (Recommended for Visuals)

**This approach uses Nano Banana Pro AI for diagram generation with Gemini 3 Pro quality review.**

**How it works:**
- Describe your diagram in natural language
- Nano Banana Pro generates publication-quality images automatically
- **Gemini 3 Pro reviews quality** against document-type thresholds
- **Smart iteration**: Only regenerates if quality is below threshold
- Professional output in minutes
- No coding, templates, or manual drawing required

**Quality Thresholds by Document Type:**
| Document Type | Threshold | Description |
|---------------|-----------|-------------|
| specification | 8.5/10 | Technical specs, PRDs |
| architecture | 8.0/10 | Architecture documents |
| proposal | 8.0/10 | Business proposals |
| sprint | 7.5/10 | Sprint planning docs |
| presentation | 6.5/10 | Slides, talks |
| default | 7.5/10 | General purpose |

## When to Use This Skill

This skill should be used when:
- Creating system architecture diagrams (C4 model, microservices, etc.)
- Illustrating data flow and integration patterns
- Drawing sequence diagrams for API interactions
- Visualizing database schemas and data models
- Creating deployment architecture diagrams (AWS, GCP, Azure)
- Depicting component relationships and dependencies
- Generating network topologies and infrastructure layouts
- Illustrating CI/CD pipelines and deployment workflows

## Quick Start: Generate Any Diagram

```bash
# System architecture (highest quality: 8.5/10)
python .claude/skills/project-diagrams/scripts/generate_schematic.py "Microservices architecture with API gateway, auth service, user service, and PostgreSQL" -o diagrams/architecture.png --doc-type specification

# C4 Context diagram
python .claude/skills/project-diagrams/scripts/generate_schematic.py "C4 Context diagram showing e-commerce system with payment gateway, inventory, customers" -o diagrams/c4_context.png --doc-type architecture

# Sequence diagram
python .claude/skills/project-diagrams/scripts/generate_schematic.py "Sequence diagram: user authentication flow with client, API, auth service, database" -o diagrams/auth_sequence.png

# Data flow diagram
python .claude/skills/project-diagrams/scripts/generate_schematic.py "Data flow: user input -> API -> validation -> business logic -> database -> response" -o diagrams/data_flow.png

# AWS deployment
python .claude/skills/project-diagrams/scripts/generate_schematic.py "AWS deployment: Route53 -> CloudFront -> ALB -> ECS Fargate -> RDS Aurora" -o diagrams/aws_deployment.png
`