← nyxcore-systems
4 min read

Bringing LLM Reports to Life: Visualizing Insights with Mermaid Diagrams

We've supercharged our LLM-generated reports by integrating Mermaid diagrams, making complex insights visually digestible and easier to understand. Dive into how we taught our AI to draw!

LLMAIGenerative AIMermaidData VisualizationTypeScriptReport GenerationDeveloper Experience

In the world of AI-generated content, clarity and comprehensibility are king. Our LLM-powered reports are fantastic at distilling complex information into concise text, but let's be honest: sometimes, a picture truly is worth a thousand tokens. That's why our latest sprint had a clear mission: integrate Mermaid diagrams into our LLM-generated reports to add a powerful visual layer to our textual insights.

I'm thrilled to report: mission accomplished! This feature is now live, committed, and ready to transform how our users consume critical information.

The Vision: Beyond Text, Towards Clarity

Imagine an executive summary that doesn't just tell you about market share, but shows you a pie chart. Or a security report that illustrates a potential attack flow with a clear flowchart. This was the driving force behind integrating Mermaid. Mermaid's simple, text-based syntax makes it a perfect fit for LLMs, allowing us to describe diagrams in a way the AI can easily understand and generate.

Our goal wasn't just to add diagrams, but to add meaningful diagrams that enhance the specific context of each report.

How We Taught Our LLM to Draw

The core of this enhancement revolved around intelligent prompt engineering and leveraging existing infrastructure. Here’s a breakdown of the key steps:

1. Tailoring Visuals to Report Styles

One of the most crucial aspects was ensuring the LLM generated relevant diagrams for each report type. We achieved this by enhancing our STYLE_TEMPLATES in src/server/services/report-generator.ts. Each template (executive, security, marketing, technical) now includes specific instructions for the LLM on which Mermaid diagram types to consider.

For example, an executive report might lean towards pie charts for market distribution, while a security report would benefit from flowcharts depicting processes or component graphs illustrating system architecture. This contextual guidance ensures that the visuals are always on-point.

2. Setting the Rules: The MERMAID_GUIDANCE

Generating diagrams without constraints can lead to cluttered, unreadable visuals. To prevent this, we introduced a MERMAID_GUIDANCE constant. This constant injects a set of clear rules directly into the LLM's system prompt:

  • Simplicity First: Max 15 nodes per diagram.
  • Concise Labels: Short, descriptive labels for nodes.
  • Clean Syntax: No special characters in node labels (e.g., backticks, quotes).
  • Placement: Diagrams should be inline with the text.
  • Moderation: Aim for 2-3 diagrams per report to avoid visual overload.

This guidance is paramount for ensuring the generated diagrams are not only syntactically correct but also genuinely helpful and easy to digest.

3. Prompt Injection: Guiding the Generator

With our templates enhanced and our rules defined, the next step was to ensure the LLM received this information. We injected the MERMAID_GUIDANCE directly into the system prompt assembly within our generateReport() function. This ensures that every time a report is generated, the LLM is fully aware of its visual responsibilities and constraints.

4. Frontend: A Seamless Integration

Perhaps the most satisfying part of this entire process was discovering that our frontend required zero changes! Our src/components/markdown-renderer.tsx already had robust support for rendering ```mermaid code blocks, thanks to our MermaidDiagram component. This component intelligently lazy-loads Mermaid v11.12.3 and applies a dark theme, ensuring diagrams look great out-of-the-box. This pre-existing capability was a huge win, allowing us to focus purely on the backend generation logic.

Lessons Learned & Operational Notes

This session was remarkably smooth, largely due to the single-file prompt change and clean type-checking. It's always a good day when a significant feature can be implemented with minimal friction.

However, a recurring operational note for our team, unrelated to this feature but always good to remember: running db:push can sometimes drop the embedding vector(1536) column on our workflow_insights table. It's a known quirk that requires manual restoration afterward. Something to keep an eye on for future schema management improvements!

What's Next? Ensuring Robustness

While the core functionality is complete, our immediate next steps involve rigorous quality assurance:

  1. Rendering Verification: Generating reports across all styles to confirm Mermaid diagrams render correctly in the preview modal.
  2. Style-Specific Diagram Types: Testing all four report styles (executive, security, marketing, technical) to ensure each receives the appropriate diagram types as per our STYLE_TEMPLATES.
  3. Error Handling: Verifying that MermaidDiagram component gracefully handles any Mermaid syntax errors, falling back to displaying the raw code block if necessary.
  4. Token Management: Considering increasing maxTokens from 4096 if the inclusion of Mermaid diagrams starts causing truncation in longer, more detailed reports.

Conclusion

Integrating Mermaid diagrams into our LLM-generated reports is a significant leap forward in making complex information more accessible and understandable. By intelligently guiding our AI through prompt engineering and leveraging existing frontend capabilities, we've added a powerful visual dimension to our reports. This not only enhances the user experience but also unlocks new possibilities for how we communicate insights.

We're excited to see this feature in action and look forward to the richer, more insightful reports it will enable!