feat: add 8 module-specific architecture diagrams (Mermaid)

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

Author: travisjneuman

concepts/diagrams/async-event-loop.md

@@ -0,0 +1,157 @@
+# Async Event Loop Deep Dive — Diagrams
+
+[<- Back to Diagram Index](../../guides/DIAGRAM_INDEX.md)
+
+## Overview
+
+These diagrams go deeper into how Python's asyncio event loop schedules coroutines, manages task lifecycles, and coordinates concurrent operations with `gather()` and `wait()`.
+
+## Event Loop Internals
+
+The event loop maintains queues of ready and waiting tasks. Each iteration ("tick") of the loop runs all ready callbacks, checks for completed I/O, and moves newly-ready tasks into the run queue.
+
+```mermaid
+flowchart TD
+    TICK["Event Loop Tick"] --> READY{"Ready queue<br/>has tasks?"}
+    READY -->|"Yes"| RUN["Run next callback<br/>(one at a time)"]
+    RUN --> CHECK_MORE{"More ready<br/>callbacks?"}
+    CHECK_MORE -->|"Yes"| RUN
+    CHECK_MORE -->|"No"| POLL["Poll for I/O events<br/>(select/epoll/kqueue)"]
+    READY -->|"No"| POLL
+
+    POLL --> IO_DONE{"I/O completed?"}
+    IO_DONE -->|"Yes"| WAKE["Move completed tasks<br/>to ready queue"]
+    IO_DONE -->|"No"| TIMERS["Check timers<br/>(sleep, timeout)"]
+    WAKE --> TIMERS
+
+    TIMERS --> EXPIRED{"Timers expired?"}
+    EXPIRED -->|"Yes"| SCHEDULE["Schedule timer<br/>callbacks as ready"]
+    EXPIRED -->|"No"| TICK
+    SCHEDULE --> TICK
+
+    style TICK fill:#cc5de8,stroke:#9c36b5,color:#fff
+    style RUN fill:#51cf66,stroke:#27ae60,color:#fff
+    style POLL fill:#4a9eff,stroke:#2670c2,color:#fff
+    style WAKE fill:#ffd43b,stroke:#f59f00,color:#000
+```
+
+**Key points:**
+- The loop runs one callback at a time (single-threaded concurrency, not parallelism)
+- I/O polling is where the loop waits for network responses, file reads, etc.
+- Timers handle `asyncio.sleep()` and timeout deadlines
+- A "tick" is one full cycle: run ready tasks, poll I/O, check timers, repeat
+
+## Task Lifecycle States
+
+A coroutine goes through several states from creation to completion. Understanding these states helps you debug hanging tasks and cancellation behavior.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Coroutine: async def my_func()
+    Coroutine --> Task: asyncio.create_task(my_func())
+    Task --> Pending: Scheduled on event loop
+    Pending --> Running: Loop picks this task
+    Running --> Awaiting: Hits await expression
+    Awaiting --> Pending: Awaited result ready
+    Running --> Done: Return value
+    Running --> Cancelled: task.cancel() called
+    Awaiting --> Cancelled: task.cancel() called
+    Pending --> Cancelled: task.cancel() called
+    Done --> [*]: result = task.result()
+    Cancelled --> [*]: raises CancelledError
+
+    note right of Coroutine: Calling async def<br/>returns a coroutine object<br/>(does NOT start running)
+    note right of Task: create_task() wraps<br/>the coroutine and<br/>schedules it
+    note left of Cancelled: CancelledError is raised<br/>inside the coroutine at<br/>the current await point
+```
+
+**Key points:**
+- Calling an `async def` function returns a coroutine object but does NOT start executing it
+- `create_task()` wraps the coroutine in a Task and schedules it on the loop
+- Cancellation raises `CancelledError` at the coroutine's current `await` point
+- A task is "done" when it returns, raises an exception, or is cancelled
+
+## gather() vs wait() vs TaskGroup
+
+Three ways to run multiple coroutines concurrently. Each has different error handling and completion semantics.
+
+```mermaid
+flowchart TD
+    subgraph GATHER ["asyncio.gather(*coros)"]
+        G_START["Start all tasks<br/>concurrently"]
+        G_WAIT["Wait for ALL<br/>to complete"]
+        G_RESULT["Returns list of results<br/>in original order"]
+        G_ERR["If one fails:<br/>cancels others (return_exceptions=False)<br/>or returns exception in list (=True)"]
+        G_START --> G_WAIT --> G_RESULT
+        G_WAIT --> G_ERR
+    end
+
+    subgraph WAIT ["asyncio.wait(tasks, ...)"]
+        W_START["Start all tasks<br/>concurrently"]
+        W_RETURN["Returns two sets:<br/>(done, pending)"]
+        W_MODE["Control when it returns:<br/>FIRST_COMPLETED<br/>FIRST_EXCEPTION<br/>ALL_COMPLETED"]
+        W_START --> W_RETURN
+        W_RETURN --> W_MODE
+    end
+
+    subgraph TASKGROUP ["asyncio.TaskGroup() — Python 3.11+"]
+        TG_START["async with TaskGroup() as tg:<br/>    tg.create_task(coro1)<br/>    tg.create_task(coro2)"]
+        TG_WAIT["Waits at end of<br/>async with block"]
+        TG_ERR["If one fails:<br/>cancels all others,<br/>raises ExceptionGroup"]
+        TG_START --> TG_WAIT --> TG_ERR
+    end
+
+    style GATHER fill:#51cf66,stroke:#27ae60,color:#fff
+    style WAIT fill:#4a9eff,stroke:#2670c2,color:#fff
+    style TASKGROUP fill:#cc5de8,stroke:#9c36b5,color:#fff
+```
+
+**Key points:**
+- `gather()` is simplest: run tasks, get results in order. Best for "do all of these and give me all results"
+- `wait()` gives you fine-grained control: react to the first completion or first failure
+- `TaskGroup` (Python 3.11+) is the modern approach with structured concurrency and clean cancellation
+- `gather(return_exceptions=True)` collects exceptions as values instead of propagating them
+
+## Sequence: Timeout and Cancellation
+
+What happens when a task exceeds a deadline. This shows the mechanics of `asyncio.wait_for()` and how cancellation propagates.
+
+```mermaid
+sequenceDiagram
+    participant Main as Main Coroutine
+    participant Loop as Event Loop
+    participant Task as Slow Task
+    participant Timer as Timeout Timer
+
+    Main->>Loop: asyncio.wait_for(slow_task(), timeout=2.0)
+    Loop->>Task: Start slow_task()
+    Loop->>Timer: Set timer for 2.0 seconds
+
+    Note over Task: Working...<br/>await aiohttp.get(slow_url)
+    Note over Loop: Loop continues<br/>running other tasks
+
+    Timer-->>Loop: 2.0 seconds elapsed!
+    Loop->>Task: task.cancel()
+    Note over Task: CancelledError raised<br/>at current await
+
+    alt Task has try/finally
+        Note over Task: finally: cleanup()
+        Task-->>Loop: Cleanup complete
+    else No cleanup
+        Task-->>Loop: CancelledError propagates
+    end
+
+    Loop-->>Main: raises asyncio.TimeoutError
+    Note over Main: Handle timeout gracefully
+```
+
+**Key points:**
+- `wait_for()` wraps a coroutine with a deadline and cancels it if the deadline passes
+- Cancellation gives the task a chance to clean up in `try/finally` blocks
+- The caller receives `TimeoutError`, not `CancelledError`
+- Always use timeouts for network operations to prevent tasks from hanging forever
+
+---
+
+| [Back to Diagram Index](../../guides/DIAGRAM_INDEX.md) |
+|:---:|

concepts/diagrams/ci-cd-pipeline.md

@@ -0,0 +1,156 @@
+# CI/CD Pipeline — Diagrams
+
+[<- Back to Diagram Index](../../guides/DIAGRAM_INDEX.md)
+
+## Overview
+
+These diagrams show how continuous integration and continuous deployment pipelines automate code quality checks, testing, and deployment using GitHub Actions as the primary example.
+
+## Full CI/CD Pipeline Flow
+
+A CI/CD pipeline runs automatically on every push or pull request. Each stage acts as a gate: if one fails, later stages do not run, preventing broken code from reaching production.
+
+```mermaid
+flowchart LR
+    PUSH["git push / PR opened"] --> LINT["Lint & Format<br/>ruff check .<br/>black --check ."]
+    LINT -->|"Pass"| TYPE["Type Check<br/>mypy src/"]
+    TYPE -->|"Pass"| TEST["Run Tests<br/>pytest --cov"]
+    TEST -->|"Pass"| BUILD["Build<br/>docker build -t app ."]
+    BUILD -->|"Pass"| DEPLOY_STAGING["Deploy to Staging<br/>Automatic"]
+    DEPLOY_STAGING --> SMOKE["Smoke Tests<br/>Hit /health endpoint"]
+    SMOKE -->|"Pass"| GATE{"Manual Approval?"}
+    GATE -->|"Approved"| DEPLOY_PROD["Deploy to Production"]
+    GATE -->|"Skip"| DONE["Pipeline Complete"]
+    DEPLOY_PROD --> DONE
+
+    LINT -->|"Fail"| STOP1["Pipeline Stops<br/>Fix lint errors"]
+    TYPE -->|"Fail"| STOP2["Pipeline Stops<br/>Fix type errors"]
+    TEST -->|"Fail"| STOP3["Pipeline Stops<br/>Fix failing tests"]
+    BUILD -->|"Fail"| STOP4["Pipeline Stops<br/>Fix build errors"]
+
+    style PUSH fill:#cc5de8,stroke:#9c36b5,color:#fff
+    style LINT fill:#ffd43b,stroke:#f59f00,color:#000
+    style TYPE fill:#ffd43b,stroke:#f59f00,color:#000
+    style TEST fill:#4a9eff,stroke:#2670c2,color:#fff
+    style BUILD fill:#ff922b,stroke:#e8590c,color:#fff
+    style DEPLOY_STAGING fill:#51cf66,stroke:#27ae60,color:#fff
+    style DEPLOY_PROD fill:#51cf66,stroke:#27ae60,color:#fff
+    style STOP1 fill:#ff6b6b,stroke:#c92a2a,color:#fff
+    style STOP2 fill:#ff6b6b,stroke:#c92a2a,color:#fff
+    style STOP3 fill:#ff6b6b,stroke:#c92a2a,color:#fff
+    style STOP4 fill:#ff6b6b,stroke:#c92a2a,color:#fff
+```
+
+**Key points:**
+- Fast checks (lint, format) run first so you get quick feedback on simple mistakes
+- Each stage is a gate: failures stop the pipeline early, saving compute time
+- Staging deployment happens automatically; production may require manual approval
+- Smoke tests verify the deployed app actually starts and responds
+
+## GitHub Actions Workflow Structure
+
+A GitHub Actions workflow is a YAML file in `.github/workflows/`. It defines triggers, jobs, and steps. Jobs run in parallel by default; use `needs` to create dependencies.
+
+```mermaid
+flowchart TD
+    subgraph TRIGGER ["Triggers (on:)"]
+        PUSH_T["push:<br/>branches: [main]"]
+        PR_T["pull_request:<br/>branches: [main]"]
+    end
+
+    subgraph JOB_LINT ["Job: lint"]
+        LINT_1["runs-on: ubuntu-latest"]
+        LINT_2["Step: checkout code"]
+        LINT_3["Step: setup-python"]
+        LINT_4["Step: pip install ruff"]
+        LINT_5["Step: ruff check ."]
+        LINT_1 --> LINT_2 --> LINT_3 --> LINT_4 --> LINT_5
+    end
+
+    subgraph JOB_TEST ["Job: test"]
+        TEST_1["runs-on: ubuntu-latest"]
+        TEST_M["strategy: matrix<br/>python: [3.11, 3.12, 3.13]"]
+        TEST_2["Step: checkout code"]
+        TEST_3["Step: setup-python (matrix)"]
+        TEST_4["Step: pip install -r requirements.txt"]
+        TEST_5["Step: pytest --cov"]
+        TEST_1 --> TEST_M --> TEST_2 --> TEST_3 --> TEST_4 --> TEST_5
+    end
+
+    subgraph JOB_DEPLOY ["Job: deploy"]
+        DEP_1["runs-on: ubuntu-latest"]
+        DEP_2["Step: checkout code"]
+        DEP_3["Step: deploy to Railway/Render"]
+        DEP_1 --> DEP_2 --> DEP_3
+    end
+
+    PUSH_T --> JOB_LINT
+    PR_T --> JOB_LINT
+    PUSH_T --> JOB_TEST
+    PR_T --> JOB_TEST
+    JOB_LINT -->|"needs: lint"| JOB_DEPLOY
+    JOB_TEST -->|"needs: test"| JOB_DEPLOY
+
+    style TRIGGER fill:#cc5de8,stroke:#9c36b5,color:#fff
+    style JOB_LINT fill:#ffd43b,stroke:#f59f00,color:#000
+    style JOB_TEST fill:#4a9eff,stroke:#2670c2,color:#fff
+    style JOB_DEPLOY fill:#51cf66,stroke:#27ae60,color:#fff
+```
+
+**Key points:**
+- Jobs run in parallel by default: `lint` and `test` start at the same time
+- `needs:` creates dependencies: `deploy` waits for both `lint` and `test` to pass
+- Matrix strategy runs the same steps across multiple Python versions simultaneously
+- Each job gets a fresh virtual machine: no state leaks between jobs
+
+## Sequence: Pull Request Lifecycle
+
+The full lifecycle from opening a PR to merging, showing how CI checks integrate with code review.
+
+```mermaid
+sequenceDiagram
+    participant Dev as Developer
+    participant GH as GitHub
+    participant CI as GitHub Actions
+    participant Rev as Reviewer
+
+    Dev->>GH: Open Pull Request
+    GH->>CI: Trigger workflow (on: pull_request)
+
+    par Parallel Jobs
+        CI->>CI: Job: lint (ruff, black)
+        CI->>CI: Job: test (pytest, 3 Python versions)
+    end
+
+    alt All checks pass
+        CI-->>GH: Status: All checks passed
+        GH-->>Dev: Green checkmarks
+        Dev->>Rev: Request review
+        Rev->>GH: Review changes
+        Rev-->>Dev: Approve / Request changes
+
+        alt Approved
+            Dev->>GH: Merge PR
+            GH->>CI: Trigger deploy workflow (on: push to main)
+            CI->>CI: Build and deploy to production
+            CI-->>GH: Deployment successful
+        end
+    else Some checks fail
+        CI-->>GH: Status: Checks failed
+        GH-->>Dev: Red X marks
+        Dev->>Dev: Fix issues locally
+        Dev->>GH: Push fix commits
+        GH->>CI: Re-trigger workflow
+    end
+```
+
+**Key points:**
+- CI runs automatically when a PR is opened and on every subsequent push to the PR branch
+- Merge is blocked until all required checks pass (configurable in branch protection rules)
+- Deploying on merge to `main` means every merged PR goes to production automatically
+- Failed checks give immediate feedback: fix and push again to re-trigger
+
+---
+
+| [Back to Diagram Index](../../guides/DIAGRAM_INDEX.md) |
+|:---:|