feat: add D2 theme support and update documentation with architecture diagrams

- Introduced 'astro-d2' package and integrated D2 theme overrides for light and dark modes
- Updated documentation to include detailed D2 architecture and task lifecycle diagrams
- Modified package.json to include 'astro-d2' dependency
- Enhanced Astro configuration with new theme settings and diagrams for better clarity

Author: jumski

.github/actions/setup-d2/action.yml

@@ -0,0 +1,23 @@
+name: 'Setup D2'
+description: 'Install D2 diagramming tool with retry logic'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Install D2
+      shell: bash
+      run: |
+        for i in 1 2 3 4 5; do
+          echo "Attempt $i to install D2..."
+          if curl -fsSL https://d2lang.com/install.sh | sh -s --; then
+            echo "D2 installed successfully"
+            break
+          else
+            if [ $i -eq 5 ]; then
+              echo "Failed to install D2 after 5 attempts"
+              exit 1
+            fi
+            echo "Install failed, retrying in 5 seconds..."
+            sleep 5
+          fi
+        done

.github/workflows/ci.yml

@@ -44,6 +44,8 @@ jobs:
       - name: Set Nx SHAs for affected commands
         uses: nrwl/nx-set-shas@v4
 
+      - uses: ./.github/actions/setup-d2
+
       - name: Quality gate (lint + typecheck + test)
         run: pnpm nx affected -t lint typecheck test --parallel --configuration=production
 
@@ -112,7 +114,9 @@ jobs:
 
       - name: Set Nx SHAs for affected commands
         uses: nrwl/nx-set-shas@v4
-      
+
+      - uses: ./.github/actions/setup-d2
+
       - name: Check if website is affected
         id: check-affected
         run: |

pkgs/website/.gitignore

@@ -19,4 +19,7 @@ pnpm-debug.log*
 
 # macOS-specific files
 .DS_Store
+
+# generated files
 public/edge-worker/
+public/d2/

pkgs/website/astro.config.mjs

@@ -6,6 +6,7 @@ import starlightLinksValidator from 'starlight-links-validator';
 import starlightSidebarTopics from 'starlight-sidebar-topics';
 import robotsTxt from 'astro-robots-txt';
 import starlightLlmsTxt from 'starlight-llms-txt';
+import d2 from 'astro-d2';
 import { fileURLToPath } from 'url';
 import path from 'path';
 
@@ -80,6 +81,42 @@ export default defineConfig({
   },
 
   integrations: [
+    d2({
+      themeId: 0, // neutral theme as base
+      themeOverrides: {
+        // pgflow brand colors for light theme
+        B1: "#007b6e", // accent
+        B2: "#a3d4cb", // accent-high
+        B3: "#bce0d9", // accent-low
+        B4: "#e7f0ee", // gray-1
+        B5: "#c2cdca", // gray-2
+        B6: "#92a8a3", // gray-3
+
+        AA2: "#003b34", // accent-high (dark)
+        AA4: "#00574d", // accent (dark)
+        AA5: "#495d59", // gray-4
+
+        AB4: "#2a3d39", // gray-5
+        AB5: "#182b28", // gray-6
+      },
+      darkThemeId: 0,
+      darkThemeOverrides: {
+        // pgflow brand colors for dark theme
+        B1: "#007b6e", // accent
+        B2: "#a3d4cb", // accent-high
+        B3: "#002b26", // accent-low
+        B4: "#2a3d39", // gray-5
+        B5: "#495d59", // gray-4
+        B6: "#92a8a3", // gray-3
+
+        AA2: "#a3d4cb", // accent-high
+        AA4: "#007b6e", // accent
+        AA5: "#c2cdca", // gray-2
+
+        AB4: "#e7f0ee", // gray-1
+        AB5: "#ffffff", // white
+      },
+    }),
     react({
       include: ['**/components/**/*.tsx'],
       exclude: ['**/pages/**/*'],

pkgs/website/package.json

@@ -27,6 +27,7 @@
     "@types/react-dom": "^19.1.7",
     "@vercel/analytics": "^1.5.0",
     "astro": "^5.7.14",
+    "astro-d2": "^0.8.0",
     "astro-robots-txt": "^1.0.0",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",

pkgs/website/src/content/docs/concepts/how-pgflow-works.mdx

@@ -27,7 +27,41 @@ pgflow follows four core design principles:
 
 ## 1. Three thin layers
 
-<img src="/diagrams/three-layers.svg" alt="Three layers of pgflow architecture: TypeScript DSL, SQL Core, and Worker" width="90%" />
+```d2
+direction: down
+
+Build-time: {
+  dsl: "TypeScript DSL" {
+    shape: document
+  }
+  
+  sql: "SQL migration" {
+    shape: stored_data
+  }
+  
+  dsl -> sql: "npx pgflow compile"
+}
+
+Runtime Postgres: {
+  label: "Run-time (inside Postgres)"
+  
+  core: "SQL Core" {
+    shape: diamond
+  }
+}
+
+Runtime Worker: {
+  label: "Run-time (outside Postgres)"
+  
+  worker: "Edge Worker" {
+    shape: cloud
+  }
+}
+
+# Connections
+Build-time.sql -> Runtime Postgres.core
+Runtime Worker.worker -> Runtime Postgres.core: "poll for work &\nreport results"
+```
 
 Layer cheat-sheet:
 
@@ -80,6 +114,49 @@ created → started → completed
 
 Behind the scenes, when a step becomes ready, workers handle the execution through a simple 3-call sequence:
 
+```d2
+direction: down
+
+Step Lifecycle: {
+  step: "Step: created → started → completed" {
+    shape: hexagon
+  }
+}
+
+Task Execution: {
+  label: "Task Execution (inside Postgres)"
+  
+  queue: "pgmq Queue" {
+    shape: cylinder
+  }
+  
+  core: "SQL Core" {
+    shape: diamond
+  }
+  
+  tasks: "step_tasks table" {
+    shape: sql_table
+  }
+}
+
+Worker Process: {
+  worker: "Edge Worker" {
+    shape: cloud
+  }
+}
+
+# Connections
+Step Lifecycle.step -> Task Execution.tasks: creates
+Step Lifecycle.step -> Task Execution.queue: enqueues
+
+Worker Process.worker -> Task Execution.queue: "1. read_with_poll"
+Worker Process.worker -> Task Execution.core: "2. start_tasks"
+Worker Process.worker -> Task Execution.core: "3. complete_task/fail_task"
+
+Task Execution.core -> Task Execution.tasks: updates
+Task Execution.core -> Step Lifecycle.step: advances
+```
+
 1. `read_with_poll` → locks queue messages  
 2. `start_tasks` → marks task started, builds input  
 3. `complete_task/fail_task` → finishes task, moves step forward