Add architecture primer (#125)

* docs: add new architecture overview documentation for pgflow

Introduce a comprehensive MDX page explaining pgflow's layered architecture,
state management, execution cycle, and type safety features.
This update
provides detailed diagrams, code examples, and explanations to improve
understanding of the core concepts and workflow orchestration model.

* docs: clarify architecture overview, core principles, and runtime behavior of pgflow

- Updated description of pgflow's architecture emphasizing Postgres as the single source of truth
- Added details on core design principles: Postgres-first, opinionated defaults, robustness,
and safety
- Clarified runtime table categories and transaction guarantees
- Included explanations of task input composition and database-driven orchestration benefits
- Enhanced notes on retry logic, error handling, and scalability features
- Improved overall documentation clarity and consistency

* docs: update architecture overview content and formatting for clarity

- Corrected quotation marks for consistency in the documentation
- Improved phrasing for better readability and professionalism
- Clarified the description of pgflow's transaction guarantees and model
- Fixed minor formatting issues in code snippets and notes
- Updated the core mental model explanation for better understanding

* docs: update documentation to clarify pgflow architecture and improve navigation

- Renamed architecture overview file to the more accurate 'how-pgflow-works.mdx'
- Updated the page title, description, and sidebar order for better clarity
- Added a new link card for 'Understanding Flow DSL' in the concepts index
- Minor formatting adjustments for consistency and readability

* docs: remove architecture overview documentation file

Deleted the 'architecture-overview.mdx' file containing high-level system architecture details,
likely to be replaced or relocated in future updates.

* docs: add placeholders for architecture diagrams and improve flow code comments

- Inserted diagram placeholders for build-time, runtime, and execution cycle
- Updated notes for clarity on queue processing and flow pattern
- Minor formatting adjustments in flow definition code for consistency

* chore: add a script to compile Mermaid diagrams to SVG with custom theme and background

This commit introduces a new executable script that automates the conversion of Mermaid
diagram files into SVG images.
The script handles input validation, creates output
directories as needed, and applies a dark theme with a specific background color during
the compilation process.
It streamlines diagram generation for the website project.

* feat: add new execution cycle diagram SVG to website assets

- Introduced a new SVG diagram illustrating the execution cycle
- Updated project assets with the SVG file in the public diagrams directory
- No code logic or functionality changes, purely asset addition

* chore: remove execution-cycle SVG diagram file

* chore: update SVG diagrams for consistency and clarity

Refactored two SVG files by replacing the previous diagrams with updated versions.
- Improved visual consistency and layout of the flowchart diagrams
- Ensured proper formatting and structure of SVG code
- Removed redundant or outdated SVG content to enhance clarity

Author: jumski

pkgs/website/bin/mmdc-compile

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# Check if an argument was provided
+if [ $# -eq 0 ]; then
+  echo "Usage: $0 <path-to-mermaid-file>"
+  exit 1
+fi
+
+# Get the input file path
+input_file="$1"
+
+# Check if the input file exists
+if [ ! -f "$input_file" ]; then
+  echo "Error: File '$input_file' not found"
+  exit 1
+fi
+
+# Extract the basename without extension
+basename=$(basename "$input_file" .mermaid)
+
+# Create output directory if it doesn't exist
+mkdir -p public/diagrams
+
+# Output file path
+output_file="public/diagrams/${basename}.svg"
+
+# Compile the mermaid file to SVG
+mmdc --theme dark --output "$output_file" --backgroundColor '#121a19' < "$input_file"
+
+echo "Compiled $input_file to $output_file"

pkgs/website/public/diagrams/three-layers.svg

@@ -0,0 +1,14 @@
+graph TD
+    subgraph "Build-time"
+      DSL[TypeScript DSL]
+      DSL -->|npx pgflow compile| SQL[SQL migration]
+    end
+    subgraph "Run-time (inside Postgres)"
+      CORE["SQL Core"]
+    end
+    subgraph "Run-time (outside Postgres)"
+      WORKER["Edge Worker"]
+    end
+    SQL --> CORE
+    WORKER -->|poll_for_tasks| CORE
+    WORKER -->|complete_task or fail_task| CORE