Skip to content
vizzy vizzy

Introduction

vizzy is a native macOS app that renders architecture, sequence, and flow diagrams from Markdown files. The diagrams live in the repo right next to the code, and the app live-reloads as the files change.

Where diagrams live

Section titled “Where diagrams live”

Diagrams are plain Markdown files in a vizzy/ folder at the repo root — one concern per file:

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

vizzy auto-discovers git repos that contain vizzy/*.vizzy.md files. One file is one “page”: prose plus one or more diagrams, shown top-to-bottom on an infinite, pannable canvas.

How a file is rendered

Section titled “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

Section titled “Next steps”