From 4d28f286db5b39864c78a12708114d8189cfc2e1 Mon Sep 17 00:00:00 2001
From: David Gwilliam <dhgwilliam@gmail.com>
Date: Mon, 16 Mar 2026 01:54:05 -0700
Subject: [PATCH] docs: add pipeline documentation with mermaid diagrams

- Add docs/PIPELINE.md with comprehensive pipeline flowchart
- Document camera modes (vertical, horizontal, omni, floating)
- Update AGENTS.md with pipeline documentation instructions
---
 AGENTS.md        |  11 ++++-
 docs/PIPELINE.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 128 insertions(+), 1 deletion(-)
 create mode 100644 docs/PIPELINE.md

diff --git a/AGENTS.md b/AGENTS.md
index ebec48e..6f9eafa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -227,4 +227,13 @@ Performance regression tests are in `tests/test_benchmark.py` with `@pytest.mark
 - C&C uses separate ntfy topics for commands and responses
 - `NTFY_CC_CMD_TOPIC` - commands from cmdline.py
 - `NTFY_CC_RESP_TOPIC` - responses back to cmdline.py
-- Effects controller handles `/effects` commands (list, on/off, intensity, reorder, stats)
\ No newline at end of file
+- Effects controller handles `/effects` commands (list, on/off, intensity, reorder, stats)
+
+### Pipeline Documentation
+
+The rendering pipeline is documented in `docs/PIPELINE.md` using Mermaid diagrams.
+
+**IMPORTANT**: When making significant architectural changes to the rendering pipeline (new layers, effects, display backends), update `docs/PIPELINE.md` to reflect the changes:
+1. Edit `docs/PIPELINE.md` with the new architecture
+2. If adding new SVG diagrams, render them manually using an external tool (e.g., Mermaid Live Editor)
+3. Commit both the markdown and any new diagram files
\ No newline at end of file
diff --git a/docs/PIPELINE.md b/docs/PIPELINE.md
new file mode 100644
index 0000000..843aef1
--- /dev/null
+++ b/docs/PIPELINE.md
@@ -0,0 +1,118 @@
+# Mainline Pipeline
+
+## Content to Display Rendering Pipeline
+
+```mermaid
+flowchart TD
+    subgraph Sources["Data Sources"]
+        RSS[("RSS Feeds")]
+        Poetry[("Poetry Feed")]
+        Ntfy[("Ntfy Messages")]
+        Mic[("Microphone")]
+    end
+
+    subgraph Fetch["Fetch Layer"]
+        FC[fetch_all]
+        FP[fetch_poetry]
+        Cache[(Cache)]
+    end
+
+    subgraph Prepare["Prepare Layer"]
+        MB[make_block]
+        Strip[strip_tags]
+        Trans[translate]
+    end
+
+    subgraph Scroll["Scroll Engine"]
+        CAM[Camera]
+        NH[next_headline]
+        RTZ[render_ticker_zone]
+        Grad[lr_gradient]
+        VT[vis_trunc / vis_offset]
+    end
+
+    subgraph Effects["Effect Pipeline"]
+        subgraph EffectsPlugins["Effect Plugins"]
+            Noise[NoiseEffect]
+            Fade[FadeEffect]
+            Glitch[GlitchEffect]
+            Firehose[FirehoseEffect]
+            Hud[HudEffect]
+        end
+        EC[EffectChain]
+        ER[EffectRegistry]
+    end
+
+    subgraph Render["Render Layer"]
+        RL[render_line]
+        TL[apply_ticker_layout]
+    end
+
+    subgraph Display["Display Backends"]
+        TD[TerminalDisplay]
+        PD[PygameDisplay]
+        SD[SixelDisplay]
+        KD[KittyDisplay]
+        WSD[WebSocketDisplay]
+        ND[NullDisplay]
+    end
+
+    Sources --> Fetch
+    RSS --> FC
+    Poetry --> FP
+    FC --> Cache
+    FP --> Cache
+    Cache --> MB
+    Strip --> MB
+    Trans --> MB
+    MB --> NH
+    NH --> RTZ
+    CAM --> RTZ
+    Grad --> RTZ
+    VT --> RTZ
+    RTZ --> EC
+    EC --> ER
+    ER --> EffectsPlugins
+    EffectsPlugins --> RL
+    RL --> Display
+    Ntfy --> RL
+    Mic --> RL
+
+    style Sources fill:#f9f,stroke:#333
+    style Fetch fill:#bbf,stroke:#333
+    style Scroll fill:#bfb,stroke:#333
+    style Effects fill:#fbf,stroke:#333
+    style Render fill:#ffb,stroke:#333
+    style Display fill:#bff,stroke:#333
+```
+
+## Camera Modes
+
+```mermaid
+stateDiagram-v2
+    [*] --> Vertical
+    Vertical --> Horizontal: mode change
+    Horizontal --> Omni: mode change
+    Omni --> Floating: mode change
+    Floating --> Vertical: mode change
+
+    state Vertical {
+        [*] --> ScrollUp
+        ScrollUp --> ScrollUp: +y each frame
+    }
+
+    state Horizontal {
+        [*] --> ScrollLeft
+        ScrollLeft --> ScrollLeft: +x each frame
+    }
+
+    state Omni {
+        [*] --> Diagonal
+        Diagonal --> Diagonal: +x, +y each frame
+    }
+
+    state Floating {
+        [*] --> Bobbing
+        Bobbing --> Bobbing: sin(time) for x,y
+    }
+```