[FEATURE] Improve diagram workflow (Mermaid-first with automated rendering)

[oehrlis]

Feature Description

Introduce a simplified and automated diagram workflow for OraDBA documentation that treats Mermaid as the default structural source and Excalidraw as an optional curated layer, with automated rendering, export, and drift detection.

The goal is to reduce manual effort, improve consistency, and keep diagrams aligned with actual script functionality while preserving high-quality visuals where needed.

Problem Statement

The current diagram workflow has several pain points:

• Mermaid diagrams must be manually copied into Excalidraw
• Three formats are maintained in parallel (.md, .excalidraw, .png)
• PNG/SVG export from Excalidraw is manual
• No automated way to detect outdated images
• Visual consistency relies on manual discipline
• High effort even for diagrams that do not need custom visuals

Current workflow:

AI / Manual Mermaid → Manual copy → Excalidraw edits → Manual PNG export

This works but does not scale and creates unnecessary maintenance overhead.

Proposed Solution

Adopt a Mermaid-first workflow with automated rendering and optional curated Excalidraw diagrams, based on a two-tier source-of-truth model:

Source of Truth Model

• Default diagrams: Mermaid (structural / functional accuracy)
• Curated diagrams: Excalidraw (visual storytelling, presentations)

Target Workflow

AI / Manual Mermaid
        ↓
Mermaid normalization (style, cleanup)
        ↓
Auto-render Mermaid → SVG (default)
        ↓
Optional: Manual Excalidraw for curated diagrams
        ↓
Auto-export SVG / PNG

Key elements

• Mermaid diagrams are auto-rendered to SVG and used directly in MkDocs and Pandoc
• Excalidraw is used only where visual customization adds value
• Excalidraw exports are automated (no manual PNG export)
• Drift detection ensures diagrams are regenerated when sources change
• Consistent visual style via shared palette, components, and Mermaid class definitions

This avoids a fragile Mermaid→Excalidraw converter while still achieving automation and consistency.

Alternative Solutions

• Full Mermaid → Excalidraw converter
  Rejected: high complexity, fragile, low ROI, difficult to maintain

• Excalidraw-only source of truth
  Rejected: diagrams drift from real script functionality and increase manual effort

• Keep current workflow
  Rejected: does not scale and remains error-prone

Environment

All environments

Usage Frequency

Weekly

Impact Level

High - Critical for my workflow

Usage Examples

# Rebuild all diagrams
make diagrams

# Check for outdated diagrams
make diagrams-check


Typical usage:

* Update Mermaid diagrams (manually or via AI)
* Run diagram build
* MkDocs + Pandoc consume generated SVG/PNG automatically

Benefits

• Significantly reduced manual work
• Diagrams stay aligned with script functionality
• Reproducible and automatable exports
• Consistent visual style across documentation
• Clear separation between “structural” and “curated” diagrams
• Lower maintenance cost over time

Additional Context

• Mermaid diagrams already exist in a single authoring Markdown file
• Excalidraw is used for customized visuals and branding
• Documentation is generated via MkDocs (GitHub Pages) and Pandoc (PDF)
• This feature focuses on workflow improvement, not visual redesign
• Proposed implementation effort: ~4–6 days, incremental and low risk

[oehrlis]

Phase 1 COMPLETE (commit 7c6be58, e875c08):

✅ Created 6 Mermaid source files in doc/images/source/
✅ Created 8 workflow Mermaid diagrams
✅ Embedded 6 diagrams in architecture.md
✅ Moved all PNG/Excalidraw files to toberemoved/
✅ Updated README.md with Mermaid-only workflow

Phase 2 IN PROGRESS:
🔄 TODO: Embed diagrams in development.md
🔄 TODO: Update user docs (src/doc/*.md)
🔄 TODO: Update MkDocs configuration for Mermaid

Phase 3 PLANNED:
📋 TODO: Pandoc integration for PDF generation (separate issue to be created)

Closing related issues #49, #50, #51 as no longer applicable with Mermaid-only approach.

[oehrlis]

Phase 1-2 COMPLETE ✅

All Mermaid migration tasks complete:

• ✅ Created 6 architecture Mermaid source files
• ✅ Embedded diagrams in architecture.md (~700 lines)
• ✅ Removed 27 legacy files (PNG/Excalidraw)
• ✅ Updated doc/images/README.md for Mermaid-only workflow
• ✅ Consolidated all 20 user documentation files for v0.19.x

Phase 3 PLANNED for v0.19.1:

• Pandoc PDF integration with Mermaid filter
• MkDocs configuration for Mermaid rendering
• PDF generation pipeline

Keeping this issue open for Phase 3 tracking.