graphviz-dive

Purpose

This skill produces exhaustive, expert-grade visualizations of any codebase. It generates complete analysis across all architectural aspects without requiring user interaction or selection.

Target: A new-grad should produce diagrams as if they'd written the system from scratch.

Core Principle

Generate ALL aspects by default. No selection, no minimal. Every diagram an expert would need to fully understand the system.

---

Complete Workflow

Step 1: Entry Point Discovery

1. Find main entry point (main.py, index.ts, main.go, etc.)
2. Identify language and framework
3. Determine project type (library, application, service)

Step 2: Module Decomposition

1. Map directory structure to module boundaries
2. Identify packages, namespaces, or module groups
3. Find configuration and dependency injection setup

Step 3: Pattern Detection

Automatically detect architecture pattern from structure:

| Pattern | Key Indicators | Files to Prioritize | |---------|----------------|---------------------| | Layered | controller/, service/, repository/ | Flow + Types | | DDD | domain/, application/, infrastructure/ | Types + Storage | | Event-Driven | events/, handlers/, queues/ | Flow + Concurrency | | Microservices | independent service directories | Context + Deployment | | Monolithic | single large codebase | All 8 aspects | | Hexagonal | ports/, adapters/, core/ | Types + Flow |

Step 4: Generate All Aspects

Always produce these 8+ diagrams:

| Aspect | File Suffix | Focus | What It Reveals | |--------|-------------|-------|-----------------| | Context | _context | External users, systems, boundaries | System scope, external deps | | Components | _components | Modules, services, boundaries | Architecture, module deps | | Types | _types | Classes, interfaces, domain model | Core abstractions, relationships | | Flow | _flow | Request pipeline, data journey | Runtime behavior, processing | | Concurrency | _concurrency | Threads, async, events | Parallelism, synchronization | | Storage | _storage | Databases, caches, schemas | Persistence, data model | | Security | _security | Auth, trust boundaries | Protection mechanisms | | Deployment | _deployment | Infrastructure, containers | Runtime environment | | Memory | _memory | Buffers, GC, pointers | Low-level efficiency (if applicable) | | State | _state | Lifecycle, transitions | Resource management |

Step 5: Expert Annotation

For each generated diagram, add analysis:

## [Diagram Name] Analysis

**Architecture Pattern Detected:** [pattern type]
**Key Design Decisions:**
  - [Decision 1] → evidenced by [component/pattern]
  - [Decision 2] → evidenced by [component/pattern]
**Critical Relationships:**
  - [A] → [B]: [why this matters for system behavior]
  - [C] → [D]: [why this matters for system behavior]
**Domain-Specific Insights:**
  - [For this pattern type, experts would focus on...]

---

Aspect Specifications

1. Context Diagram (_context.dot)

Focus: External boundaries and users

Nodes:

• External Users (end users, other systems)
• External Services (APIs, databases, message queues)
• System Boundary (the analyzed system)

Edges:

• User → System: "uses", "authenticated"
• System → External Service: "calls", "publishes"

Example:

subgraph cluster_external {
  label="External Systems";
  style="dashed,rounded";
  color="#dc3545";
  bgcolor="#fff5f5";
  
  user [label="End User", shape="person"];
  ext_api [label="Third-party API", shape="ellipse", style="dashed"];
}

subgraph cluster_system {
  label="Your System";
  style="rounded";
  color="#0d6efd";
  bgcolor="#e7f1ff";
  
  api_gateway [label="API Gateway"];
  auth_service [label="Auth Service"];
}

user -> api_gateway [xlabel="HTTPS"];
api_gateway -> auth_service [xlabel="validate"];
api_gateway -> ext_api [xlabel="REST"];

2. Components Diagram (_components.dot)

Focus: Module boundaries and internal structure

Nodes:

• Application Layer (controllers, handlers)
• Domain Layer (business logic, entities)
• Infrastructure Layer (DB, external clients)
• Shared/Kernel (utilities, constants)

Edges:

• Layer dependencies (top-down)
• Cross-cutting concerns

3. Types Diagram (_types.dot)

Focus: Class hierarchy and interfaces

Nodes:

• Abstract classes (italic label)
• Concrete classes
• Interfaces (diamond)
• Value objects

Edges:

• Inheritance (solid, arrow)
• Composition (diamond)
• Association (arrow)

4. Flow Diagram (_flow.dot)

Focus: Request lifecycle and data journey

Nodes:

• Entry points (HTTP, CLI, Worker)
• Processing stages
• Decision points (gates)
• Exit points

Edges:

• Primary flow (solid)
• Error paths (dashed)
• Async triggers

5. Concurrency Diagram (_concurrency.dot)

Focus: Parallelism and synchronization

Nodes:

• Thread/Worker pools
• Event loops
• Message queues
• Lock/Scope boundaries

Edges:

• Spawns
• Waits on
• Signals
• Locks

6. Storage Diagram (_storage.dot)

Focus: Data persistence and schemas

Nodes:

• Databases
• Tables/Collections
• Cache layers
• File stores

Edges:

• Read/Write
• Sync/Async
• Replication

7. Security Diagram (_security.dot)

Focus: Authentication and authorization

Nodes:

• Trust boundaries (dashed ovals)
• Auth mechanisms
• Permission layers
• Sensitive data stores

Edges:

• Authentication flows
• Authorization checks
• Data access

8. Deployment Diagram (_deployment.dot)

Focus: Infrastructure and scaling

Nodes:

• Servers/Containers
• Load balancers
• Service instances
• External services

Edges:

• Network paths
• Replication
• Scaling groups

---

The "ByteByteGo" Style (MUST USE)

Every file MUST include these attributes:

digraph "aspect_name" {
  // 1. Layout Engine
  layout="dot";
  rankdir="LR";
  
  // 2. Global Graph Attributes
  graph [
    fontname="Virgil";
    fontsize=20;
    splines="ortho";
    nodesep=1.0;
    ranksep=1.5;
    pad=0.5;
    style="filled";
    color="white";
    label="Diagram Title";
    labelloc="t";
  ];

  // 3. Node Attributes
  node [
    shape="box";
    style="rounded,filled";
    fillcolor="#ffffff";
    fontname="Virgil";
    fontsize=16;
    penwidth=2.0;
    color="#000000";
    margin=0.2;
  ];

  // 4. Edge Attributes
  edge [
    fontname="Virgil";
    fontsize=12;
    penwidth=1.5;
    color="#000000";
    arrowhead="vee";
  ];

  // Use xlabel for edge labels (never label!)
  node_a -> node_b [xlabel="Action"];
}

Color Reference

| Element Type | Stroke Color | Fill Color | |--------------|--------------|-------------| | External | #dc3545 (red) | #fff5f5 | | Services | #0d6efd (blue) | #e7f1ff | | Domain | #198754 (green) | #e8f5e9 | | Data | #fd7e14 (orange) | #fff3e0 | | Security | #6f42c1 (purple) | #f3e5f5 | | Infrastructure | #6c757d (grey) | #f8f9fa |

---

Expert Mental Models

How Experts Decompose Systems

1. Start at boundaries: What enters? What leaves?
2. Find the core: Where is the business logic?
3. Trace the flow: How does data move through?
4. Identify patterns: What architecture does it follow?
5. Map the scale: How does it handle load?

Questions Each Aspect Answers

| Aspect | Questions It Answers | |--------|---------------------| | Context | What depends on this? What does it depend on? | | Components | What are the major modules? How do they interact? | | Types | What are the core abstractions? How do they relate? | | Flow | How does a request move through the system? | | Concurrency | How does it handle parallelism? | | Storage | How is data persisted and accessed? | | Security | How is access controlled? | | Deployment | Where does it run? How does it scale? |

Pattern → Aspect Priority

| Pattern | Primary Aspects | Secondary Aspects | |---------|-----------------|-------------------| | Layered | Types + Flow | Components + Storage | | DDD | Types + Storage | Flow + Components | | Event-Driven | Flow + Concurrency | Context + Components | | Microservices | Context + Deployment | Components + Storage | | Monolithic | All 8 | - |

---

Output Requirements

File Naming

All output files follow: {project}_{aspect}.dot

Examples:

• myapp_context.dot
• myapp_components.dot
• myapp_types.dot
• myapp_flow.dot
• myapp_concurrency.dot
• myapp_storage.dot
• myapp_security.dot
• myapp_deployment.dot

Required Output

For every codebase analyzed, generate:

1. All 8+ .dot files
2. A summary README.md explaining:
   • Architecture pattern detected
   • Key design decisions
   • How the aspects connect
   • Domain-specific insights

---

Rendering Instructions

Always provide rendering guidance:

1. Online: Paste DOT code into Edotor.net or GraphvizOnline
2. Local: Use dot -Tsvg file.dot -o file.svg
3. Excalidraw: Convert to SVG, drag into Excalidraw for hand-drawn editing

---

Red Flags - Stop and Correct

• Edge Labels: MUST use xlabel instead of label for edges
• Curved Lines: splines="ortho" is NON-NEGOTIABLE
• Font Missing: fontname="Virgil" must be present
• Single Graph: Never try to fit all 8 aspects in one diagram
• Reserved Keywords: Never name nodes graph, node, edge

---

Reference Files

• template/ - Reusable templates for each aspect type
• examples/ - Complete multi-file examples for different architecture types