Vizo: Diagrams Should Be Code, Context, and Conversation

Every engineering team draws diagrams. Whiteboards, Lucidchart, draw.io, Figma , the tools multiply, but the problem stays the same: diagrams rot. They’re created in a burst of enthusiasm during an architecture review, exported as a PNG, dropped into Confluence, and never touched again. Within weeks, the system has moved on and the diagram is a fossil.

Vizo exists because we believe diagrams deserve the same rigour we give to source code: version control, narrative context, searchability, and a living relationship with the systems they describe.

The Philosophy: Diagrams-as-Code, Elevated

The Diagrams-as-Code movement , Mermaid, PlantUML, D2, Structurizr , was a breakthrough. It brought diagrams into text files, making them diffable, reviewable, and storable alongside the code they document. But the movement stopped short.

Writing a .mmd file and committing it to Git solves the storage problem. It doesn’t solve the understanding problem.

A sequence diagram of your payment flow is useful. But without the narrative that explains why the retry logic exists, what the edge cases are, and which assumptions were made during the design , the diagram is a picture, not knowledge.

Vizo bridges that gap.

What Makes Vizo Different

1. Narrative Persistence

Every diagram in Vizo has a linked README , a Markdown narration that travels with the diagram everywhere it goes. When you render a C4 model, the README explains the bounded contexts. When you build a sequence diagram, the README documents the protocol assumptions.

This isn’t a comment field. It’s a first-class, full-text-searchable document that is indexed alongside the diagram source. When someone searches for “payment retry”, they find the diagram and the reasoning behind it.

2. Annotations: Teaching Diagrams to Speak

Annotations let you attach structured metadata to specific elements within a diagram. Each annotation has a label, a detailed description, a colour accent, and an explicit display order.

This creates something unprecedented: play mode. You can step through a complex architecture diagram element by element, with each annotation narrating the story. It turns a static picture into a guided walkthrough , the architect’s tour of the system.

3. Polyglot by Design

Vizo doesn’t pick a favourite. It renders 13 diagram-as-code languages through a unified API:

• Mermaid , Flowcharts, sequence diagrams, Gantt charts
• D2 , Declarative diagramming with automatic layout
• PlantUML , The industry standard for UML
• C4 (PlantUML) , Simon Brown’s C4 model
• Graphviz (DOT) , The original graph description language
• Structurizr , Architecture-as-code
• BPMN , Business process modelling
• Excalidraw , Hand-drawn aesthetic diagrams
• ERD, Ditaa, BlockDiag, Nomnoml, SeqDiag , Specialised notations

You pick the language that best fits the problem. Vizo handles rendering, caching, and persistence uniformly.

4. Git-Native Workflow

Diagrams in Vizo can be linked to files in GitHub or GitLab repositories. Push a change to your .mmd file, and Vizo syncs. Edit in Vizo’s live editor, and it pushes back. The diagram lives in both worlds , the developer’s IDE and the team’s visual workspace.

Version history isn’t an afterthought. Every edit creates a versioned snapshot with commit-style metadata: who changed it, when, and why. You can diff any two versions and see a unified diff of the diagram source. You can restore any previous version with a single click.

This is Git semantics applied to visual documentation.

5. Presentations Built from Diagrams

Vizo lets you compose presentation decks from your existing diagrams. Select the diagrams, arrange the order, and you have a slide deck that’s always current , because the slides are the diagrams.

Presentation mode includes:

• Fullscreen player with keyboard navigation
• Dark and light themes
• Speaker notes pulled from diagram READMEs
• PDF export for offline distribution
• Version history for the deck itself

No more copying diagrams into PowerPoint. The presentation is a living view of your architecture.

6. Multi-Tenancy and Team Collaboration

Vizo is built for teams from the ground up. Workspaces provide complete isolation between projects and organisations. Within each workspace, role-based access control (Owner, Admin, Editor, Viewer) governs who can create, edit, and view diagrams.

Team members are invited by email, and you can switch between workspaces instantly. Each workspace has its own diagrams, presentations, and billing.

7. Cross-Service Publishing

Diagrams shouldn’t be trapped in a diagramming tool. Vizo diagrams can be published directly to the Juaji Blog with a single click, composing a blog post with the embedded SVG, the README as article content, and the source code in a collapsible block. The post is attributed to the actual user, not a generic service account.

This is the beginning of a broader vision: diagrams as a shared medium across the entire platform , documentation, blog posts, decision records, incident reports.

The Architecture Behind It

Vizo practices what it preaches. It’s built on a clean, Unix-philosophy stack:

• Go + Templ + HTMX , Server-rendered HTML with surgical DOM updates. No JavaScript framework, no build pipeline, no client-side state management. The server is the source of truth.
• Kroki , A unified rendering engine that delegates to native renderers. Vizo doesn’t try to parse Mermaid or PlantUML itself , it delegates to the best-in-class tools.
• PostgreSQL , Diagrams, narrations, versions, and teams all live in a relational database with GIN-indexed full-text search.
• Redis , Rendered SVGs are cached by content hash, so repeated renders are instant.
• Keycloak OIDC , Enterprise-grade identity with zero custom auth code.
• Lago , Metered billing that tracks renders per user, per tier.

Each component does one thing well. The system is deployed on Docker Swarm , no Kubernetes complexity tax, just reliable multi-node orchestration.

The Value Proposition

Most diagramming tools solve the drawing problem. Vizo solves the knowledge problem.

Feature	draw.io / Lucidchart	Mermaid CLI	Vizo
Visual editor	✅	❌	✅ (code + preview)
Diagrams-as-Code	❌	✅	✅ (13 languages)
Narrative context	❌	❌	✅ (README per diagram)
Version history	Limited	Git only	✅ (built-in + Git sync)
Full-text search	❌	❌	✅ (source + narration)
Presentations	❌	❌	✅ (live from diagrams)
Team RBAC	✅	❌	✅
API-first	Limited	❌	✅ (HATEOAS)
Annotations/Play mode	❌	❌	✅
Cross-publish to blog	❌	❌	✅

Vizo is for teams that treat their architecture diagrams as living documentation , not disposable whiteboard sketches.

Getting Started

Vizo is available at vizo.juaji.com. The free tier includes 20 renders per month , enough to explore the platform and see if it fits your workflow.

For teams, the Pro tier at $15/month unlocks 1,000 renders, private narrations, and full team management. Enterprise customers get metered billing at $0.02 per render with SLA guarantees.

---

Diagrams are how engineers think. Vizo makes sure that thinking is preserved, shared, and always current.