Skip to content

AvinashP/AgentsAtlas / skills/explaining-code

explaining-code

Verified

Explains code with diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when asked "how does this work?"

FileKindSize
SKILL.mdskill md5.6 KB
diagrams.mdmarkdown12.3 KB

diagrams.md

View on GitHub
# ASCII Diagram Patterns

Ready-to-use ASCII diagram patterns for explaining code.

## Basic Shapes

### Boxes and Containers

```
Simple box:
┌──────────────┐
│   Content    │
└──────────────┘

Labeled box:
┌─ Label ──────┐
│   Content    │
│   Content    │
└──────────────┘

Double border:
╔══════════════╗
║   Content    ║
╚══════════════╝

Rounded:
╭──────────────╮
│   Content    │
╰──────────────╯
```

### Arrows

```
Horizontal:    →  ─▶  ═▶
Vertical:      ↓  │   ║
               ▼  ▼   ▼
Diagonal:      ╲  ╱
Bidirectional: ↔  ⟷  ◀─▶
```

---

## Architecture Diagrams

### Client-Server

```
┌─────────┐         ┌─────────┐         ┌─────────┐
│ Browser │ ──────▶ │   API   │ ──────▶ │Database │
│ (React) │ ◀────── │ (Node)  │ ◀────── │ (Mongo) │
└─────────┘  HTTP   └─────────┘  Query  └─────────┘
```

### Microservices

```
              ┌─────────────┐
              │ API Gateway │
              └──────┬──────┘
         ┌──────────┼──────────┐
         ▼          ▼          ▼
    ┌─────────┐ ┌─────────┐ ┌─────────┐
    │  Auth   │ │  Users  │ │ Orders  │
    │ Service │ │ Service │ │ Service │
    └────┬────┘ └────┬────┘ └────┬────┘
         │          │          │
         ▼          ▼          ▼
    ┌─────────┐ ┌─────────┐ ┌─────────┐
    │  Auth   │ │  Users  │ │ Orders  │
    │   DB    │ │   DB    │ │   DB    │
    └─────────┘ └─────────┘ └─────────┘
```

### Event-Driven

```
┌──────────┐    Event    ┌──────────────┐
│ Producer │ ──────────▶ │ Message Bus  │
└──────────┘             │   (Kafka)    │
                         └──────┬───────┘
                 ┌───────────┬──┴──┬───────────┐
                 ▼           ▼     ▼           ▼
            ┌─────────┐ ┌─────────┐ ┌─────────┐
            │Consumer │ │Consumer │ │Consumer │
            │   A     │ │   B     │ │   C     │
            └─────────┘ └─────────┘ └─────────┘
```

---

## Data Flow Diagrams

### Request/Response

```
Client                    Server                    Database
  │                         │                          │
  │   1. HTTP Request       │                          │
  │ ─────────────────────▶  │                          │
  │                         │   2. SQL Query           │
  │                         │ ──────────────────────▶  │
  │                         │                          │
  │                         │   3. Result Set          │
  │                         │ ◀──────────────────────  │
  │   4. HTTP Response      │                          │
  │ ◀─────────────────────  │                          │
  │                         │                          │
```

### Pipeline

```
Input ──▶ [Stage 1] ──▶ [Stage 2] ──▶ [Stage 3] ──▶ Output
             │             │             │
             ▼             ▼             ▼
          Validate      Transform     Format
```

### State Machine

```
            start
              │
              ▼
        ┌───────────┐
        │   Idle    │◀───────────┐
        └─────┬─────┘            │
         click│                  │done
              ▼                  │
        ┌───────────┐      ┌─────┴─────┐
        │  Loading  │─────▶│  Success  │
        └─────┬─────┘      └───────────┘
         error│
              ▼
        ┌───────────┐
        │   Error   │
        └─────┬─────┘
         retry│
              │
              ▼
          (back to Idle)
```

---

## Component Diagrams

### React Component Tree

```
<App>
  │
  ├── <Header>
  │     ├── <Logo />
  │     └── <Nav>
  │           ├── <NavItem />
  │           └── <NavItem />
  │
  ├── <Main>
  │     └── <Content>
  │           ├── <Article />
  │           └── <Sidebar />
  │
  └── <Footer />
```

### Module Dependencies

```
     ┌──────────────┐
     │     App      │
     └──────┬───────┘
            │
    ┌───────┼───────┐
    ▼       ▼       ▼
┌───────┐ ┌────┐ ┌──────┐
│ Auth  │ │ UI │ │ API  │
└───┬───┘ └────┘ └───┬──┘
    │                │
    └────────┬───────┘
             ▼
         ┌───────┐
         │ Utils │
         └───────┘
```

### Class Inheritance

```
        ┌─────────────┐
        │   Animal    │
        │ ─────────── │
        │  name       │
        │  speak()    │
        └──────┬──────┘
               │
       ┌───────┴───────┐
       ▼               ▼
┌─────────────┐  ┌─────────────┐
│     Dog     │  │     Cat     │
│ ─────────── │  │ ─────────── │
│  breed      │  │  indoor     │
│  bark()     │  │  meow()     │
└─────────────┘  └─────────────┘
```

---

## Algorithm Diagrams

### Binary Tree

```
            ┌───┐
            │ 8 │
            └─┬─┘
         ┌───┴───┐
         ▼       ▼
       ┌───┐   ┌───┐
       │ 3 │   │ 10│
       └─┬─┘   └─┬─┘
       ┌─┴─┐     └─┐
       ▼   ▼       ▼
     ┌───┐ ┌───┐ ┌───┐
     │ 1 │ │ 6 │ │ 14│
     └───┘ └───┘ └───┘
```

### Stack Operations

```
Push(A):    Push(B):    Push(C):    Pop():
┌───┐       ┌───┐       ┌───┐       ┌───┐
│   │       │   │       │ C │ ──▶   │   │
├───┤       ├───┤       ├───┤       ├───┤
│   │       │ B │       │ B │       │ B │
├───┤       ├───┤       ├───┤       ├───┤
│ A │       │ A │       │ A │       │ A │
└───┘       └───┘       └───┘       └───┘
```

### Queue Operations

```
Enqueue:                    Dequeue:
   ┌───┬───┬───┬───┐           ┌───┬───┬───┬───┐
   │ A │ B │ C │ D │ ◀── in    │   │ B │ C │ D │
   └───┴───┴───┴───┘           └───┴───┴───┴───┘
        out ──▶                       out ──▶ A
```

---

## Sequence Diagrams

### Simple Sequence

```
User          Frontend        Backend         Database
 │               │               │               │
 │  Click        │               │               │
 │──────────────▶│               │               │
 │               │  API Call     │               │
 │               │──────────────▶│               │
 │               │               │  Query        │
 │               │               │──────────────▶│
 │               │               │  Data         │
 │               │               │◀──────────────│
 │               │  Response     │               │
 │               │◀──────────────│               │
 │  Display      │               │               │
 │◀──────────────│               │               │
```

### With Conditions

```
Client              Server
  │                    │
  │   Login Request    │
  │───────────────────▶│
  │                    │
  │                  ┌─┴─┐
  │                  │if │
  │                  │OK │
  │◀──────────────── │   │ ── Token
  │                  │   │
  │                  │else
  │◀──────────────── │   │ ── Error
  │                  └─┬─┘
  │                    │
```

---

## Memory Diagrams

### Stack vs Heap

```
Stack                    Heap
┌─────────────┐         ┌─────────────────────────┐
│ main()      │         │                         │
├─────────────┤         │  ┌─────────────────┐    │
│  x = 5      │         │  │ { name: "John"} │    │
├─────────────┤         │  └─────────────────┘    │
│  y = 10     │         │         ▲               │
├─────────────┤         │         │               │
│  obj ───────┼─────────┼─────────┘               │
├─────────────┤         │                         │
│ func()      │         │                         │
├─────────────┤         │                         │
│  a = 3      │         │                         │
└─────────────┘         └─────────────────────────┘
```

### Reference vs Value

```
Value Type:                Reference Type:
┌───┐  copy  ┌───┐         ┌───┐  copy  ┌───┐
│ 5 │ ─────▶ │ 5 │         │ ● │ ─────▶ │ ● │
└───┘        └───┘         └─┬─┘        └─┬─┘
  a            b             │            │
                             └──────┬─────┘
                                    ▼
                              ┌─────────┐
                              │ {x: 10} │
                              └─────────┘
```

---

## Quick Reference

### Common Symbols

```
Process:       ◯  □  ◇
Decision:      ◇  <>
Data:          ▱  ▭
Start/End:     ◯  ⬭
Arrow:         →  ─▶  ═▶  ⟶
```

### Box Drawing Characters

```
Corners:  ┌ ┐ └ ┘  ╔ ╗ ╚ ╝  ╭ ╮ ╰ ╯
Lines:    ─ │      ═ ║      ━ ┃
T-shapes: ┬ ┴ ├ ┤  ╦ ╩ ╠ ╣
Cross:    ┼        ╬
```
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall