Introduction to vizzy

vizzy is a native macOS app that renders architecture, sequence, flow, timeline, and mind-map diagrams from Markdown files. The files live wherever you keep them — commonly right next to your code — and the app live-reloads as they change.

Download for macOS Universal · Apple-notarized · auto-updates

Where diagrams live

A diagram is a plain *.vizzy.md Markdown file — one concern per file. Keep it wherever you like: in your code repo, a docs folder, or on its own. A tidy convention is to group a project’s diagrams in a vizzy/ folder at the repo root…

vizzy/
  architecture.vizzy.md     # high-level service / component map
  <flow>.vizzy.md           # one file per important flow (auth, checkout, …)
  vizzy.config              # optional — re-theme the standard color palette
  assets/                   # optional — images / icons referenced by diagrams

…but that’s only a convention — there’s no required folder name and no git repo needed. One file is one “page”: prose plus one or more diagrams, shown top-to-bottom on an infinite, pannable canvas.

Opening them in Vizzy

Vizzy is organized around workspaces — each a named set of folders and files you want to watch. You add what you care about explicitly, and it live-reloads as it changes:

• A single file — File ▸ Open… (⌘O), drag a .vizzy.md onto the window, or run vizzy path/to/diagram.vizzy.md in the terminal.
• A whole folder — File ▸ Add Folder…, drag it in, or run vizzy ~/Code/myproject. Vizzy scans it recursively for *.vizzy.md files — no vizzy/ folder or git repo required.

On first launch Vizzy seeds a Default workspace from the common dev folders it finds (~/Code, ~/Developer, and the like); after that, what each workspace watches is up to you.

How a file is rendered

A *.vizzy.md file is plain GitHub-Flavored Markdown:

• Prose renders as annotation cards (full Markdown — headings, lists, code, bold).
• Fenced code blocks render as diagrams. A mermaid fence holds standard Mermaid; a vizzy fence holds vizzy’s own additions (architecture maps and annotations).

---
title: Auth architecture
created: 2026-06-16
lastEdited: 2026-06-16
---

The login path, end to end.

```mermaid
flowchart LR
  web[Web] --> api[API] --> db[(Postgres)]
```

```vizzy
note api: rate limited 5/min
hint api: [Why?]("Token bucket, **5 req/min**.")
```

Next steps

• Set up an agent — let a coding agent author and maintain your diagrams.
• File format — frontmatter and the two kinds of fence.
• Diagram types — sequence, flowchart, architecture, and more.
• Present mode — step through a file’s diagrams full-screen as animated slides.
• Publish to the web — share a diagram or a whole workspace at a public usevizzy.com link.
• Rendering to images — the vizzy CLI for exporting diagrams as PNG, JPEG, HEIC, or AVIF.