ASCII Diagram Skill

SKILL.md

name	description
ascii-diagram	Create ASCII architecture diagrams, system designs, tables, and technical illustrations using box-drawing characters. Use when asked to draw diagrams, visualize architecture, create flowcharts, or illustrate system components.

ASCII Architecture Diagrams

Create clean, professional ASCII diagrams for system architecture, flowcharts, tables, and technical documentation.

When to Use This Skill

• Visualizing system architecture
• Creating flowcharts or process diagrams
• Drawing network topologies
• Making tables with borders
• Illustrating data flow
• Documenting component relationships
• Creating technical diagrams for documentation

Core Principles

1. Use Unicode box-drawing characters for clean, professional appearance
2. Maintain alignment with consistent spacing and column widths
3. Layer components to show hierarchy and relationships
4. Add shadows (░ character) for depth
5. Use consistent styles within a single diagram
6. Label clearly with concise text inside or near components

Box Drawing Characters Reference

Single Line Boxes

┌─────────┐
│  Title  │
└─────────┘

Corners: ┌ ┐ └ ┘
Lines:   ─ │
T-joints: ┬ ┴ ├ ┤
Cross:    ┼

Double Line Boxes (Emphasis)

╔═════════╗
║  Title  ║
╚═════════╝

Corners: ╔ ╗ ╚ ╝
Lines:   ═ ║
T-joints: ╦ ╩ ╠ ╣
Cross:    ╬

Rounded Boxes (Softer Look)

╭─────────╮
│  Title  │
╰─────────╯

Corners: ╭ ╮ ╰ ╯

Heavy/Thick Boxes

┏━━━━━━━━━┓
┃  Title  ┃
┗━━━━━━━━━┛

Corners: ┏ ┓ ┗ ┛
Lines:   ━ ┃

Shadows (3D Effect)

╔═════════╗
║  Title  ║░
╚═════════╝░
 ░░░░░░░░░░

Shadow character: ░

Arrows and Connectors

Simple Arrows

──▶  ◀──  (horizontal)
  │
  ▼      (vertical)
  │
  ▲

Alternative: → ← ↑ ↓

Labeled Connections

Component A ───HTTP──▶ Component B

Component A ════API═══▶ Component B

Bidirectional

Component A ◀────▶ Component B

Component A ◀═══▶ Component B

Example 1: System Architecture with Nested Components

                        ╔═ turbopuffer ════════════════════════════╗
╔════════════╗          ║                                          ║░
║            ║░         ║  ┏━━━━━━━━━━━━━━━┓     ┏━━━━━━━━━━━━━━┓  ║░
║   client   ║░───API──▶║  ┃    Memory/    ┃────▶┃    Object    ┃  ║░
║            ║░         ║  ┃   SSD Cache   ┃     ┃ Storage (S3) ┃  ║░
╚════════════╝░         ║  ┗━━━━━━━━━━━━━━━┛     ┗━━━━━━━━━━━━━━┛  ║░
 ░░░░░░░░░░░░░░         ║                                          ║░
                        ╚══════════════════════════════════════════╝░
                         ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

Key Features:

• Double-line outer box (╔═╗) for main service
• Heavy-line inner boxes (┏━┓) for components
• Simple shadows (░) for depth
• Clear API connection with labeled arrow
• Title integrated into top border

Example 2: Table with Borders

┌─ Limits ────────────────────────────────────────────────────────────────────┐
│ Metric                                    Observed in production            │
├─────────────────────────────────────────────────────────────────────────────┤
│ Max documents (global)                    11T+ @ 1PB                        │
│ Max documents (queried simultaneously)    100B+ @ 10TB                      │
│ Max documents (per namespace)             500M+ @ 2TB                       │
│ Max number of namespaces                  100M+                             │
│ Max write throughput (global)             10M+ writes/s @ 32GB/s            │
│ Max write throughput (per namespace)      32k+ writes/s @ 64MB/s            │
│ Max queries (global)                      10k+ queries/s                    │
│ Max queries (per namespace)               1k+ queries/s                     │
└─────────────────────────────────────────────────────────────────────────────┘

Key Features:

• Title in top border
• Header separator with ├─┤
• Single-line style for clean readability
• Properly aligned columns
• Simple and readable design

Example 3: Three-Tier Web Architecture

                  ┌─────────────────┐
                  │   Web Browser   │
                  └────────┬────────┘
                           │ HTTPS
                           ▼
            ╔══════════════════════════╗
            ║   Load Balancer (ALB)    ║
            ╚════════════╦═════════════╝
                         ║
         ┌───────────────╬───────────────┐
         │               │               │
         ▼               ▼               ▼
   ┏━━━━━━━━━┓     ┏━━━━━━━━━┓     ┏━━━━━━━━━┓
   ┃  Web 1  ┃     ┃  Web 2  ┃     ┃  Web 3  ┃
   ┃ (EC2)   ┃     ┃ (EC2)   ┃     ┃ (EC2)   ┃
   ┗━━━━┳━━━━┛     ┗━━━━┳━━━━┛     ┗━━━━┳━━━━┛
        │               │               │
        └───────────────┼───────────────┘
                        │
                        ▼
               ╔════════════════╗
               ║   PostgreSQL   ║░
               ║   Primary DB   ║░
               ╚════════════════╝░
                ░░░░░░░░░░░░░░░░░░

Key Features:

• Double-line boxes (╔═╗) for infrastructure components
• Heavy-line boxes (┏━┓) for application servers
• Shadows (░) on database for emphasis
• Clear flow from top to bottom
• Labeled connections showing protocol

Example 4: Write-Ahead Log (WAL) Pattern

                                User Write
                                 ┌─────┐
                                 │█████│
             WAL                 │█████│
 s3://tpuf/{namespace_id}/wal    └──┬──┘
                                    │
                                    │
╔═══════════════════════════════════╬══════════════╗
║┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌ ─│─ ┐           ║░
║│█████│ │█████│ │█████│ │█████│    ▼              ║░
║│█████│ │█████│ │█████│ │█████│ │     │           ║░
║└─────┘ └─────┘ └─────┘ └─────┘  ─ ─ ─            ║░
║  001     002     003     004     005             ║░
╚══════════════════════════════════════════════════╝░
 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

Key Features:

• Shows user writing data into a WAL segment
• Numbered segments (001-005) for sequential writes
• Filled blocks (█) to indicate data
• Dashed box for the current write target
• Cross junction (╬) for data flow into container

Example 5: Distributed System with Load Balancer and Object Storage

                   ╔══turpuffer region═══════╗      ╔═══Object Storage═════════════════╗
                   ║      ┌────────────────┬─╬─┐    ║ ┏━━Indexing Queue━━━━━━━━━━━━━━┓ ║░
                   ║      │ ./tpuf indexer │ ║░│    ║ ┃■■■■■■■■■                     ┃ ║░
                   ║      └────────────────┘ ║░│    ║ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ║░
                   ║      ┌────────────────┐ ║░│    ║ ┏━/{org_id}/{namespace}━━━━━━━━┓ ║░
                   ║      │ ./tpuf indexer │ ║░│    ║ ┃ ┏━/wal━━━━━━━━━━━━━━━━━━━━━┓ ┃ ║░
                   ║      └────────────────┘ ║░└───▶║ ┃ ┃■■■■■■■■■■■■■■■◈◈◈◈       ┃ ┃ ║░
                   ║                         ║░     ║ ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┃ ║░
                   ║                         ║░┌───▶║ ┃ ┏━/index━━━━━━━━━━━━━━━━━━━┓ ┃ ║░
                   ║      ┌────────────────┐ ║░│    ║ ┃ ┃■■■■■■■■■■■■■■■           ┃ ┃ ║░
                   ║   ┌─▶│  ./tpuf query  │ ║░│    ║ ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┃ ║░
                ┌──╩─┐ │  └────────────────┘ ║░│    ║ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ║░
╔══════════╗    │    │ │  ┌────────────────┐ ║░│    ╚══════════════════════════════════╝░
║  Client  ║───▶│ LB │─┼─▶│  ./tpuf query  │─╬─┘     ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
╚══════════╝░   │    │ │  └────────────────┘ ║░
 ░░░░░░░░░░░░   └──╦─┘ │  ┌────────────────┐ ║░
                   ║   └─▶│  ./tpuf query  │ ║░
                   ║      └────────────────┘ ║░
                   ║                         ║░
                   ╚═════════════════════════╝░
                    ░░░░░░░░░░░░░░░░░░░░░░░░░░░

Key Features:

• Multiple nested layers showing storage hierarchy
• Load balancer (LB) distributing to query servers
• Indexer processes writing to object storage
• Progress indicators (■ and ◈) showing queue status
• Complex routing with multiple connection types
• Deep nesting: region → services, storage → namespace → wal/index

Best Practices

1. Plan Before Drawing

• Sketch component hierarchy
• Identify main vs. secondary components
• Determine flow direction (usually left-to-right or top-to-bottom)

2. Use Consistent Styles

• Main services: Double-line boxes (╔═╗)
• Sub-components: Heavy-line boxes (┏━┓)
• Containers/groups: Single-line boxes (┌─┐)
• External systems: Rounded boxes (╭─╮)

3. Maintain Spacing

• Align boxes vertically and horizontally
• Use consistent padding inside boxes
• Keep arrow lengths similar for parallel connections

4. Add Context

• Label connections (HTTP, API, Data, etc.)
• Number steps in sequence diagrams
• Use shadows for main components only

5. Keep It Simple

• Don't overcomplicate - clarity over detail
• Group related components
• Use whitespace effectively

6. Common Patterns

Request-Response:

Client ──request──▶ Server
       ◀─response──

Pub-Sub:

Publisher ──▶ Message Queue ──▶ Subscriber 1
                    │
                    ├──▶ Subscriber 2
                    │
                    └──▶ Subscriber 3

Master-Replica:

        ┌────────┐
        │ Master │
        └───┬────┘
            │
    ┌───────┼───────┐
    │       │       │
    ▼       ▼       ▼
┌────────┐ ┌────────┐ ┌────────┐
│Replica │ │Replica │ │Replica │
│   1    │ │   2    │ │   3    │
└────────┘ └────────┘ └────────┘

Quick Reference: Building Blocks

Box:          ┌───────┐
              │ Text  │
              └───────┘

Emphasized:   ╔═══════╗
              ║ Text  ║
              ╚═══════╝

With Shadow:  ┌───────┐
              │ Text  │░
              └───────┘░
               ░░░░░░░░

Arrow:        ────▶

Connection:   ┌───┐
              │ A │────┐
              └───┘    │
                       ▼
              ┌───┐  ┌───┐
              │ B │  │ C │
              └───┘  └───┘

Tips for Success

1. Start simple - Add complexity gradually
2. Test alignment - View in monospace font
3. Use proper Unicode - Don't mix ASCII and box-drawing
4. Group logically - Related components should be visually close
5. Iterate - Adjust spacing and alignment as needed

Character Palette

For quick copy-paste:

Box Drawing:  ─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼
              ═ ║ ╔ ╗ ╚ ╝ ╠ ╣ ╦ ╩ ╬
              ━ ┃ ┏ ┓ ┗ ┛ ┣ ┫ ┳ ┻ ╋
              ─ │ ╭ ╮ ╰ ╯

Arrows:       → ← ↑ ↓ ▶ ◀ ▲ ▼ ⇒ ⇐ ⇑ ⇓

Shading:      ░ ▒ ▓ █

Misc:         • ○ ◆ ◇ ■ □ ▪ ▫