feat: add 10 advanced concept diagram files (Mermaid)

HTTP, API, async, testing, generators, collections, functools/itertools,
terminal, regex, and security — each with 2-4 focused Mermaid diagrams
for GitHub rendering.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: travisjneuman

concepts/diagrams/api-basics.md

@@ -0,0 +1,157 @@
+# Diagrams: API Basics
+
+[Back to concept](../api-basics.md)
+
+---
+
+## REST API Architecture
+
+A REST API sits between the client and the database. It receives HTTP requests, processes them, and returns JSON responses.
+
+```mermaid
+flowchart LR
+    subgraph CLIENTS ["Clients"]
+        PY["Python script<br/>requests.get()"]
+        WEB["Web browser<br/>fetch()"]
+        MOB["Mobile app<br/>HTTP client"]
+    end
+
+    subgraph API ["REST API Server"]
+        ROUTER["Router<br/>Match URL to handler"]
+        AUTH["Auth middleware<br/>Verify token/key"]
+        HANDLER["Route handler<br/>Business logic"]
+        SERIAL["Serializer<br/>Dict to JSON"]
+    end
+
+    subgraph DATA ["Data Layer"]
+        DB[("Database<br/>PostgreSQL")]
+        CACHE[("Cache<br/>Redis")]
+    end
+
+    PY -->|"HTTP request"| ROUTER
+    WEB -->|"HTTP request"| ROUTER
+    MOB -->|"HTTP request"| ROUTER
+
+    ROUTER --> AUTH
+    AUTH --> HANDLER
+    HANDLER --> DB
+    HANDLER --> CACHE
+    DB --> SERIAL
+    SERIAL -->|"JSON response"| PY
+    SERIAL -->|"JSON response"| WEB
+    SERIAL -->|"JSON response"| MOB
+
+    style CLIENTS fill:#4a9eff,stroke:#2670c2,color:#fff
+    style API fill:#cc5de8,stroke:#9c36b5,color:#fff
+    style DATA fill:#51cf66,stroke:#27ae60,color:#fff
+```
+
+## CRUD to HTTP Method Mapping
+
+REST maps the four database operations (Create, Read, Update, Delete) to HTTP methods and URL patterns.
+
+```mermaid
+flowchart TD
+    subgraph CRUD ["Database Operation"]
+        CREATE["CREATE<br/>Insert new row"]
+        READ["READ<br/>Select rows"]
+        UPDATE["UPDATE<br/>Modify row"]
+        DELOP["DELETE<br/>Remove row"]
+    end
+
+    subgraph HTTP ["HTTP Method + URL"]
+        POST["POST /users<br/>Body: {name, email}"]
+        GET1["GET /users<br/>List all"]
+        GET2["GET /users/42<br/>Get one"]
+        PUT["PUT /users/42<br/>Body: {name, email}"]
+        DEL["DELETE /users/42<br/>No body"]
+    end
+
+    subgraph RESPONSE ["Response"]
+        R201["201 Created<br/>{id: 43, name: ...}"]
+        R200L["200 OK<br/>[{id: 1}, {id: 2}, ...]"]
+        R200O["200 OK<br/>{id: 42, name: ...}"]
+        R200U["200 OK<br/>{id: 42, name: ...}"]
+        R204["204 No Content"]
+    end
+
+    CREATE --> POST --> R201
+    READ --> GET1 --> R200L
+    READ --> GET2 --> R200O
+    UPDATE --> PUT --> R200U
+    DELOP --> DEL --> R204
+
+    style CRUD fill:#ff922b,stroke:#e8590c,color:#fff
+    style HTTP fill:#4a9eff,stroke:#2670c2,color:#fff
+    style RESPONSE fill:#51cf66,stroke:#27ae60,color:#fff
+```
+
+## API Request/Response Flow
+
+Step-by-step sequence of a typical API call from Python using the `requests` library.
+
+```mermaid
+sequenceDiagram
+    participant Script as Python Script
+    participant Lib as requests library
+    participant API as API Server
+    participant Logic as Route Handler
+
+    Script->>Lib: requests.post(url, json=data, headers=headers)
+    Note over Lib: Serialize dict to JSON<br/>Add Content-Type header
+
+    Lib->>API: POST /users HTTP/1.1<br/>Authorization: Bearer eyJ...<br/>Content-Type: application/json<br/>{"name": "Alice", "email": "..."}
+
+    API->>API: Validate auth token
+    API->>Logic: Call create_user handler
+
+    Note over Logic: Validate input<br/>Insert into database<br/>Build response
+
+    Logic-->>API: {"id": 43, "name": "Alice"}
+    API-->>Lib: HTTP/1.1 201 Created<br/>Content-Type: application/json
+
+    Lib-->>Script: Response object
+
+    Note over Script: response.status_code → 201<br/>response.json() → {"id": 43, ...}
+```
+
+## Authentication Token Flow
+
+How bearer token authentication works: login once, then include the token with every request.
+
+```mermaid
+sequenceDiagram
+    participant Client as Python Client
+    participant API as API Server
+    participant DB as User Database
+
+    Note over Client: Step 1: Login to get a token
+
+    Client->>API: POST /auth/login<br/>{"username": "alice", "password": "s3cret"}
+    API->>DB: Verify credentials
+    DB-->>API: User found, password matches
+
+    Note over API: Generate JWT token<br/>Encode user ID + expiry
+
+    API-->>Client: 200 OK<br/>{"token": "eyJhbGci...", "expires_in": 3600}
+
+    Note over Client: Save the token
+
+    Note over Client: Step 2: Use token for API calls
+
+    Client->>API: GET /users/me<br/>Authorization: Bearer eyJhbGci...
+
+    Note over API: Decode token<br/>Verify signature<br/>Check expiry
+
+    API-->>Client: 200 OK<br/>{"id": 1, "name": "Alice", "role": "admin"}
+
+    Note over Client: Step 3: Token expires
+
+    Client->>API: GET /users/me<br/>Authorization: Bearer eyJhbGci...
+
+    Note over API: Token expired!
+
+    API-->>Client: 401 Unauthorized<br/>{"detail": "Token expired"}
+
+    Note over Client: Must login again<br/>to get a new token
+```

concepts/diagrams/async-explained.md

@@ -0,0 +1,136 @@
+# Diagrams: Async Explained
+
+[Back to concept](../async-explained.md)
+
+---
+
+## Event Loop State Machine
+
+The event loop is the engine that runs async code. It cycles through coroutines, running whichever one is ready and pausing those that are waiting.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Created: async def called
+    Created --> Scheduled: asyncio.create_task()
+    Scheduled --> Running: Event loop picks it up
+    Running --> Suspended: Hits await (I/O, sleep)
+    Suspended --> Scheduled: Awaited operation completes
+    Running --> Done: Returns a value
+    Running --> Error: Raises exception
+    Done --> [*]
+    Error --> [*]
+
+    note right of Running: Only ONE coroutine<br/>runs at a time
+    note right of Suspended: Event loop runs<br/>other tasks while waiting
+```
+
+## Async/Await Execution Flow
+
+This shows how three concurrent tasks share a single thread. The event loop switches between them whenever one hits an `await`.
+
+```mermaid
+sequenceDiagram
+    participant Loop as Event Loop
+    participant A as Task A (fetch user)
+    participant B as Task B (fetch posts)
+    participant C as Task C (fetch comments)
+
+    Note over Loop: asyncio.gather(A, B, C)
+
+    Loop->>A: Start Task A
+    Note over A: Send HTTP request
+    A-->>Loop: await response (I/O wait)
+
+    Loop->>B: Start Task B
+    Note over B: Send HTTP request
+    B-->>Loop: await response (I/O wait)
+
+    Loop->>C: Start Task C
+    Note over C: Send HTTP request
+    C-->>Loop: await response (I/O wait)
+
+    Note over Loop: All 3 requests in flight<br/>Loop waits for first completion
+
+    Note over B: Response arrives first!
+    Loop->>B: Resume Task B
+    Note over B: Parse JSON, return data
+    B-->>Loop: Task B done
+
+    Note over A: Response arrives
+    Loop->>A: Resume Task A
+    Note over A: Parse JSON, return data
+    A-->>Loop: Task A done
+
+    Note over C: Response arrives
+    Loop->>C: Resume Task C
+    Note over C: Parse JSON, return data
+    C-->>Loop: Task C done
+
+    Note over Loop: All tasks complete<br/>Total time ≈ slowest task
+```
+
+## Concurrent vs Parallel Execution
+
+Concurrent means tasks take turns on one thread. Parallel means tasks literally run at the same time on multiple cores.
+
+```mermaid
+flowchart TD
+    subgraph SYNC ["Synchronous (blocking)"]
+        direction LR
+        S1["Task A<br/>1 sec"] --> S2["Task B<br/>1 sec"] --> S3["Task C<br/>1 sec"]
+    end
+    SYNC_TIME["Total: 3 seconds"]
+
+    subgraph CONCURRENT ["Concurrent (asyncio)"]
+        direction LR
+        CA["Task A starts"] -.->|"await"| CB["Task B starts"] -.->|"await"| CC["Task C starts"]
+        CC -.->|"all complete"| CDONE["All done"]
+    end
+    CONC_TIME["Total: ~1 second<br/>One thread, interleaved"]
+
+    subgraph PARALLEL ["Parallel (multiprocessing)"]
+        direction LR
+        PA["Core 1: Task A"]
+        PB["Core 2: Task B"]
+        PC["Core 3: Task C"]
+    end
+    PAR_TIME["Total: ~1 second<br/>Multiple cores, truly simultaneous"]
+
+    SYNC --- SYNC_TIME
+    CONCURRENT --- CONC_TIME
+    PARALLEL --- PAR_TIME
+
+    style SYNC fill:#ff6b6b,stroke:#c92a2a,color:#fff
+    style CONCURRENT fill:#51cf66,stroke:#27ae60,color:#fff
+    style PARALLEL fill:#4a9eff,stroke:#2670c2,color:#fff
+    style SYNC_TIME fill:#ff6b6b,stroke:#c92a2a,color:#fff
+    style CONC_TIME fill:#51cf66,stroke:#27ae60,color:#fff
+    style PAR_TIME fill:#4a9eff,stroke:#2670c2,color:#fff
+```
+
+## When to Use Which Approach
+
+A decision tree for choosing between sync, async, and multiprocessing.
+
+```mermaid
+flowchart TD
+    START["What kind of work?"] --> Q1{"Waiting on I/O?<br/>(network, files, DB)"}
+
+    Q1 -->|"Yes"| Q2{"Multiple I/O<br/>operations?"}
+    Q1 -->|"No"| Q3{"CPU-heavy?<br/>(math, image processing)"}
+
+    Q2 -->|"Yes"| ASYNC["Use asyncio<br/>async/await + gather()"]
+    Q2 -->|"No, just one"| SYNC_OK["Plain sync is fine<br/>requests.get()"]
+
+    Q3 -->|"Yes"| Q4{"Need shared memory?"}
+    Q3 -->|"No"| SYNC["Plain sync is fine<br/>No concurrency needed"]
+
+    Q4 -->|"Yes"| THREAD["Use threading<br/>with locks"]
+    Q4 -->|"No"| MULTI["Use multiprocessing<br/>One process per core"]
+
+    style ASYNC fill:#51cf66,stroke:#27ae60,color:#fff
+    style SYNC_OK fill:#4a9eff,stroke:#2670c2,color:#fff
+    style SYNC fill:#4a9eff,stroke:#2670c2,color:#fff
+    style THREAD fill:#ffd43b,stroke:#f59f00,color:#000
+    style MULTI fill:#cc5de8,stroke:#9c36b5,color:#fff
+```