Core Ideas
Files Are Canonical
ASCII Diagram treats the filesystem as canonical and the app state as derived.
That means:
- the
.asciidfile is the source of truth - the editor UI is replaceable
- rendered ASCII is an output, not the only source
- caches and local UI state can be rebuilt
This is the practical meaning of file > app.
Structured Source, Text Output
ASCII Diagram is not just a raw ASCII text editor.
The canonical file is structured JSON with objects, relations, groups, metadata, and versioned schema information. The app uses that structure to provide:
- snapping
- arrow routing
- grouping
- property editing
- stable IDs for future tooling
From that structured source, the app can render plain ASCII output when you need it.
Infinite Character Grid
There is no stored canvas size.
Objects live at arbitrary grid coordinates, including negative coordinates if needed. This matters because diagrams often start small and then expand in one direction as the idea gets clearer.
You do not need to migrate from "small canvas mode" to "large canvas mode." The grid is the space.
Relations Matter
ASCII Diagram stores relationships between objects separately from the objects themselves.
That allows arrows to stay attached to boxes, text blocks, or other arrows while the diagram changes. It is a small design choice with big ergonomic consequences.
Reviewable By Default
Because the source is file-based, normal software workflows apply:
- keep diagrams in Git
- review them in PRs
- back them up with the rest of your project
- keep them next to the docs they support
Canonical vs. derived state
ASCII Diagram draws a clear line between what is canonical and what is derived:
| Canonical | Derived |
|---|---|
.asciid source file | Rendered ASCII |
| object metadata | local selection state |
| relations and groups | viewport position |
| diagram name and timestamps | panel openness and transient UI |
If you lose the UI state, you lose convenience. If you keep the file, you keep the diagram.
Local-first
ASCII Diagram is useful without an account, sync backend, or import pipeline.
The app should help you work with your files, not pressure you into handing them over.