DiaStream

DiaStream helps you turn technical systems into interactive diagrams that people can explore, edit, and play through.

Diagrams that explain themselves: interactive, easy to create and refine, scenario-aware, embeddable anywhere, and readable by both people and AI.

Explore the live demo →

Every diagram is saved as structured Diagram JSON, so it stays editable and portable. DiaStream turns that data into an interactive SVG experience in the browser.

DiaStream normalizes saved documents into a canonical form with explicit edge, animation, and group defaults. The same JSON therefore carries its behavior without relying on hidden runtime defaults.

🚧 Project status: DiaStream is an early public prototype. Diagram JSON currently uses schemaVersion: "0.2", and its APIs and file format may change before the first stable release.

🌟 Why DiaStream?

• 💡 Self-explanatory. A diagram should communicate its structure and behavior without requiring a separate wall of text. Labels, visual hierarchy, animation, and scenes should work together to explain the system.
• 🖱️ Interactive by default. A diagram should be explored, inspected, zoomed, and played rather than consumed as a fixed image.
• ✏️ Easy to create and refine. Start from a structured draft, then adjust nodes, connections, layout, labels, and behavior visually without losing the underlying model.
• 🎬 Scenario-driven. Use the same architecture to explain normal operation, failures, retries, recovery, and other changes over time.
• 🌍 Embed anywhere. Diagrams should remain interactive inside technical blogs, documentation, websites, and wikis instead of being exported only as static images.
• 🤖 Readable by people and AI. Diagram JSON gives humans, editors, validators, and language models one explicit format they can all inspect and modify.

These principles describe the product direction. The local editor, scene runtime, standalone self-hosted viewer, and first public LLM skills are available for local use today.

✨ What Works Today

• Schema-validated Diagram JSON with semantic reference checks
• Deterministic SVG rendering from Diagram JSON
• Pan, zoom, and an adaptive canvas grid
• Node creation, cascading deletion, selection, editing, dragging, and Shift-based multi-selection
• A bundled Material Symbols node icon catalog with a searchable visual picker
• Edge creation, deletion, selection, and editing, including markers, routing, line styles, colors, and labels
• Scene creation, ordering, metadata editing, playback, and animated data-flow examples
• Scene-scoped node and edge property overrides with visual change indicators and reset controls
• Local New diagram, Open, Save, and Save as workflows
• Dirty-state tracking and unsaved-page warnings
• A standalone self-hosted iframe viewer with scene navigation at /viewer/?src=...
• Runtime, editor, and schema packages with regression tests

🚀 Quick Start

Requirements

• Node.js 24 or later
• npm

The required Node.js major version is recorded in .nvmrc.

Run Locally

git clone https://github.com/gyugyu90/DiaStream.git
cd DiaStream
nvm install
nvm use
npm install
npm run dev

Open http://127.0.0.1:5173/ in a browser.

The first screen is the local editor entry point for opening an existing .diagram.json file or creating a new empty document. Diagram JSON files under outputs/ are automatically listed on this page; refresh after adding a file while the development server is running. Bundled examples are available at http://127.0.0.1:5173/examples.

💾 Work with Local Files

1. Select Open to load an existing .diagram.json file, or select New diagram to create an empty schema-valid document.
2. Add, select, move, edit, or delete nodes and edit supported edge properties on the canvas.
3. With npm run dev, select a document from outputs/ and use Save to overwrite that source file. Files opened through the browser's File System Access API can also use Save directly. Other files use Save as to download the current document as a .diagram.json file.
4. Reopen that file later to continue editing.

Opened files are validated against both the structural schema and cross-document reference rules. Invalid JSON, missing or malformed fields, duplicate IDs, and broken references are reported in the application.

The outputs/ write path is available only from the local Vite development server. A deployed static editor has no server-side file write capability, so it continues to use the browser upload and download flow.

🧩 Diagram JSON

Diagram JSON is a project-defined format, not an existing standard. Its main document model is:

Diagram
|- Metadata
|- Viewport
|- Theme
|- Nodes
|- Edges
|- Groups
|- Animations
`- Scenes

Each node, edge, animation, group, and scene has a stable ID. References between those entities are checked when a document is parsed.

See the following resources:

• Diagram JSON design draft
• Self-hosted embedding guide
• Advanced self-hosting and Netlify deployment guide
• JSON Schema
• Basic web architecture example
• Circuit breaker scenes example
• PKCE OAuth2 flow example

The Zod definition in packages/schema/src/index.ts is the schema source of truth. schemas/diagram.schema.json is generated from it and should not be edited by hand.

npm run schema:generate     # Regenerate the public JSON Schema
npm run schema:check        # Fail when the generated file is out of sync
npm run diagrams:normalize # Canonicalize Diagram JSON files
npm run diagrams:normalize:check # Check that bundled examples are canonical
npm run diagrams:validate   # Run structural and reference-integrity checks on examples

🤖 LLM Skills

DiaStream includes two service-neutral skills that work with local files and the repository schema:

• create-diagram creates a new schema-valid Diagram JSON file from an architecture or scenario description.
• update-diagram locates an existing diagram by exact path, filename, metadata title, or a title mentioned in the prompt, then updates it without breaking IDs and references.

Codex automatically discovers these repository-scoped skills from .agents/skills when it runs inside this repository. Invoke them with prompts such as $create-diagram Draw a web checkout architecture or $update-diagram title: "Web Checkout" Add a retry queue after the worker.

To use the skills from other repositories, symlink them into the user-scoped skill directory while keeping them connected to this clone:

mkdir -p "$HOME/.agents/skills"
ln -s "$PWD/.agents/skills/create-diagram" "$HOME/.agents/skills/create-diagram"
ln -s "$PWD/.agents/skills/update-diagram" "$HOME/.agents/skills/update-diagram"

Other LLM tools can use the instructions in each SKILL.md without authentication or a hosted DiaStream service. If a newly added skill does not appear in Codex, restart Codex and reopen the repository.

Both skills target schemaVersion: "0.2" and run the repository validator before completing a change. create-diagram writes to outputs/ by default, so its result appears on the local editor home page after refresh. Keep the skills, examples, and schema documentation synchronized when the contract changes.

🏗️ Project Structure

apps/
  demo/       Local DiaStream application and example gallery

packages/
  schema/     Diagram JSON types, structural validation, and reference validation
  runtime/    Read-only SVG rendering, viewport behavior, and scene playback
  editor/     Selection, dragging, property editing, and edit history

examples/     Bundled example .diagram.json documents
outputs/      Default local workspace for generated .diagram.json documents
schemas/      Generated public JSON Schema
scripts/      Schema generation and Diagram JSON validation tools
.agents/
  skills/     Repository-scoped LLM skills for creating and updating Diagram JSON
docs/         Format and testing documentation

The package namespace remains @diastream/* for now. These packages are workspace packages and are not yet documented as a stable public npm API.

🛠️ Build and Test

npm run dev      # Start the local Vite development server
npm test         # Run the Vitest suite
npm run build    # Type-check packages and build the demo
npm run check    # Check schema sync, validate examples, test, and build
npm run preview  # Preview the production build locally

Changes to the schema, renderer output, editor behavior, or local document workflow should include regression tests. See the testing policy for the expected test layers.

🚀 Deployment

The local editor entry point is served at /, the sample gallery is served at /examples, the self-hosted iframe viewer is served at /viewer/?src=..., and each diagram editor uses /diagrams/:diagramId/edit. Static hosts must rewrite client-side routes to index.html.

npm run build also packages self-hosted embed examples and every outputs/**/*.diagram.json file into dist/diagrams/, plus the iframe test page in dist/embed/. Upload the generated dist/ directory to a static host and open /embed/ to verify iframe embedding with the bundled diagrams.

To deploy a diagram created in the local editor, follow the advanced self-hosting guide. It explains where to place local Diagram JSON files, how they are copied into dist/, and how to configure Git-based Netlify deployment.

GitHub Pages

This repository publishes the current main branch to gyugyu90.github.io/DiaStream through GitHub Actions. The Pages build uses the /DiaStream/ project-site path and includes a 404.html fallback so direct links to editor routes keep working. In the repository's Settings → Pages, select GitHub Actions as the publishing source before the first deployment.

To reproduce the Pages output locally:

npm run build:pages

For AWS Amplify Hosting, add the following 200 rewrite under Rewrites and redirects so direct editor links and browser refreshes continue to load the application while static assets remain untouched:

[
  {
    "source": "</^[^.]+$|\\.(?!(css|gif|ico|jpg|js|png|txt|svg|woff|woff2|ttf|map|json|webp)$)([^.]+$)/>",
    "status": "200",
    "target": "/index.html",
    "condition": null
  }
]

🚧 Good to Know

• Edge creation currently connects nodes; selecting explicit source and target ports is not yet available.
• Deleting a node from the diagram also deletes every edge connected to it.
• Direct Save is available only when the browser exposes the File System Access API.
• Groups can be rendered from Diagram JSON, but group authoring is not yet available in the editor.
• Scenes currently share diagram-wide nodes and edges. Scene edit scope can override their properties and positions, but it cannot yet add, hide, or delete topology for one scene only.
• The prompt field does not call an AI service.
• The iframe viewer is self-hosted and read-only. Script embed and React SDK options are not available yet.
• Unsupported schema versions produce compatibility errors. The migration entry point exists, but no cross-version migration path is registered yet.

🗺️ Where DiaStream Is Heading

Here is what comes next for the local-first experience:

1. Define scene-specific node and edge visibility, creation, and deletion behavior.
2. Add group authoring and port-aware edge creation.
3. Verify responsive iframe rendering and expand static-hosting deployment guidance.

🤝 Contributing

DiaStream is being developed in public. Focused issues and pull requests are welcome, especially for schema correctness, renderer compatibility, editor usability, accessibility, testing, and self-hosted embedding.

Before submitting a change:

1. Keep the change within the existing schema, runtime, editor, or demo ownership boundary.
2. Add regression coverage for behavior changes and bug fixes.
3. Run npm run check.
4. Update the relevant documentation when changing Diagram JSON or a public contract.

📄 License

DiaStream is available under the MIT License. Selected Material Symbols assets are distributed under Apache 2.0; see Third-Party Notices.