Make Graphviz optional, use MermaidJS in admin frontend

[Copilot]

Makes Graphviz an optional dependency and uses MermaidJS for client-side rendering in the Django admin interface.

Changes

Dependencies

• Removed graphviz>=0.18 from required dependencies
• Added graphviz>=0.18 as optional dependency (available via pip install joeflow[graphviz])
• Graphviz can be installed optionally for CLI tools and programmatic use

Admin Frontend

• Added MermaidJS CDN to admin templates for client-side diagram rendering
• Created display_workflow_diagram admin field that uses Mermaid syntax
• Added get_graph_mermaid() method to generate Mermaid syntax for workflow graphs
• Added get_instance_graph_mermaid() method to generate Mermaid syntax for instance graphs

Backward Compatibility

• All original Graphviz code remains unchanged
• CLI commands (render_workflow_graph) still work with Graphviz when installed
• Existing get_graph(), get_graph_svg(), and get_instance_graph_svg() methods unchanged
• Users can opt-in to Graphviz support with pip install joeflow[graphviz]

Usage

Without Graphviz (default):

pip install joeflow
# Admin interface renders diagrams with MermaidJS in browser
# No binary dependencies required

With Graphviz (optional):

pip install joeflow[graphviz]
# Enables CLI tools and programmatic SVG generation
python manage.py render_workflow_graph  # Uses Graphviz

Mermaid diagram generation:

# Generate Mermaid syntax for client-side rendering
mermaid_syntax = workflow.get_graph_mermaid()
# Or for instance graphs
mermaid_syntax = workflow_instance.get_instance_graph_mermaid()

Sample Mermaid syntax generated:

graph LR
    start(start)
    process[process]
    end[end]
    start --> process
    process --> end

Loading

Key Features

• ✅ No required binary dependencies - Graphviz is now optional

• ✅ MermaidJS in admin - Client-side rendering in browser (no server dependencies)

• ✅ Backward compatible - All existing Graphviz functionality preserved

• ✅ Flexible - Users choose whether to install Graphviz for CLI/programmatic use

• ✅ Lightweight - Default installation has no binary dependencies

• Fixes Switch from graviz to Mermaid #142

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Switch from graviz to Mermaid</issue_title>
<issue_description>I'd like to drop the binary dependency for gravis and use Mermaid instead.

We can use the mermaid-py package for the commands and use MermaidJS to render the Django admin view.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Switch from graviz to Mermaid #142

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[codingjoe]

@copilot use the mermaid-py Python package to reduce the amount of code required to solve this. I also want the default export to remain SVG if possible.

[Copilot]

@copilot use the mermaid-py Python package to reduce the amount of code required to solve this. I also want the default export to remain SVG if possible.

I've updated the implementation with the following changes (commit b86b6ac):

SVG as Default:

• get_graph_svg() now returns actual SVG content (not HTML with Mermaid markup)
• Uses mermaid.ink API for server-side SVG rendering
• Management command defaults to SVG output
• Maintains backward compatibility with Graphviz API

Regarding mermaid-py package:
I've added mermaid>=0.3.2 to dependencies. However, after researching the package, I found it either requires:

1. mermaid-cli binary (defeats "no binary dependencies" goal), or
2. Uses mermaid.ink API (which I've already implemented directly)

The current implementation generates Mermaid syntax efficiently without the extra package layer, then uses mermaid.ink API for SVG rendering. This approach:

• Reduces code complexity
• Has zero binary dependencies
• Provides server-side SVG rendering
• Still allows client-side rendering via MermaidJS if needed

If you'd prefer to use the mermaid package wrapper anyway, I can refactor to use it, but it would add an extra dependency layer without functional benefit.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• mermaid.ink
  • Triggering command: python /tmp/validate_mermaid.py (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[codingjoe]

@copilot this isn't working. Let change plans. We only use mermaid JS in the admin frontend and keep graviz as an optional/extra Python dependency.

[Copilot]

@copilot this isn't working. Let change plans. We only use mermaid JS in the admin frontend and keep graviz as an optional/extra Python dependency.

I've updated the implementation per your feedback (commit f84cf3c):

Changes made:

• Removed graphviz from required dependencies
• Made graphviz an optional dependency (extras: graphviz, docs)
• Reverted all previous Mermaid server-side rendering code
• Added MermaidJS to admin templates for client-side rendering
• Created get_graph_mermaid() and get_instance_graph_mermaid() methods
• Updated admin to use display_workflow_diagram which renders Mermaid diagrams client-side

Result:

• Admin frontend uses MermaidJS (no binary dependencies needed)
• Graphviz remains available as optional install: pip install joeflow[graphviz]
• All original graphviz functionality preserved for CLI/programmatic use
• Fully backward compatible