Model Weave

日本語版: README-ja.md

Model Weave is an Obsidian plugin for reading design information written in Markdown as diagrams, previews, diagnostics, and source links. Markdown files are the source of truth. From those files, Model Weave generates views such as ER diagrams, Class diagrams, DFDs, business flows, and data definitions.

What is Model Weave?

Model Weave brings structured software modeling capabilities to Obsidian.

It helps keep design assets human-readable, Git-friendly, and usable as structured context for AI-assisted implementation, documentation, and review.

What can you use it for?

• Structural design: ER diagrams and Class diagrams.
• Data flow: DFDs and Data Object definitions.
• Application logic: App Process business flows, Screen definitions, and Business Rules.
• Impact analysis: Automatically detect relationships and dependencies across the design.

Recent updates in 0.1.22

• Primary View places the current model and its derived Weave Map side by side as selectable top-level views. Weave Map remains an ImpactSummary -> WeaveMapModel -> Mermaid source relationship and impact view, not a Markdown format.
• Applied Color Scheme is now a visual Color Legend in Details, with grouped target rows, fill/stroke/text swatches, and configured or built-in source badges.
• Flow Diagram diagnostics distinguish local Objects.id endpoints from external references, so local node IDs no longer create false-positive external-reference diagnostics or impact links.
• Declarative Settings support Obsidian 1.13+ settings search while preserving the existing Settings display for earlier Obsidian versions.

Basic idea

Start from what you need

You do not need to learn every model format first.

Whether you are working with a simple class definition or a complex data flow, you can start with only the model type needed for your current task.

From rough manual design to AI-assisted detailed modeling

Model Weave supports a wide range of workflows, from rough manual design to detailed AI-assisted modeling.

You can start with simple prose or rough notes, then refine them into structured tables as the design matures.

Automatically generate diagrams for design review

Focus on writing the design in text.

Model Weave automatically renders diagrams for overview checks and relationship review using Custom or Mermaid renderers.

Use design documents as a map to find source code

With Source Links, design documents can become a navigation map.

You can jump from documentation to actual implementation files, including files outside the vault when configured.

First things to try

1. Install and enable the plugin.
2. Open a sample file from the samples/ directory.
3. Run the modeling preview and check the diagram and diagnostics.
4. Click related objects in the preview to navigate through the design.

First commands to use

Open the Obsidian command palette (Ctrl+P / Cmd+P) and search for Model Weave.

Try these commands first:

• Model Weave: Open modeling preview for active file: Preview the active model as a diagram or structured view.
• Model Weave: Rebuild modeling index: Rebuild relationship information across the vault.
• Model Weave: Export Current Diagram as PNG: Export the current diagram as a PNG file.

In Obsidian's command palette, commands are shown with the plugin name prefix Model Weave:. Search for Model Weave to find them.

Where to go next

• Getting Started - A 5-minute tutorial.
• Command Guide - Full command and template reference.
• Roadmap - Current direction and exploratory work.
• Format Guide - How to write each model type.
• Samples - Example models and diagrams.
• Japanese README - Japanese version of this document.

Technical reference summary

Core principles

• Markdown is the source of truth.
• Mermaid, SVG, and PNG are generated views.
• Custom renderers are for detailed review; Mermaid renderers are for overview.

Rendering policy

• render_mode: supported values depend on the format. For example, class / ER formats support custom, mermaid, and mermaid-detail; dfd_diagram and flow_diagram support mermaid; domains and domain_diagram support mindmap, area, and tree.
• Initial priority: supported frontmatter render_mode > format-specific settings default > built-in fallback.
• Toolbar renderer selection is temporary for the current view only.
• See V0.8 rendering policy for details.

Main formats

• Stable: class, er_entity, dfd_diagram, data_object, and others.
• Evolving: flow_diagram, screen, app_process, rule, codeset, and others.

Installation

Starting with 0.1.16, Model Weave requires Obsidian 1.8.7 or later.

1. Open Obsidian Settings > Community plugins.
2. Search for Model Weave.
3. Install and enable the plugin.

Viewer behavior

• Supports zoom, fit, pan, Focus mode, View Only mode, and real-time diagnostics.
• Resolved nodes and boxes in supported Model Weave views can show hover previews and can be clicked to open their source Markdown. Unresolved nodes, labels, edges, and field rows may not be interactive.
• Hover previews rely on Obsidian's hover-link / Page Preview behavior. They may not appear near the top edge of the Obsidian window or while using Model Weave Focus mode. Use click navigation as the reliable fallback for resolved nodes.
• PNG export captures only the diagram body.

Source Links

Source Links can point to external implementation files.

Relative paths are resolved using the localSourceRoot setting. This desktop-only setting is explicitly chosen by the user to resolve Source Links to local implementation files outside the vault; Model Weave does not use it to manage general external storage.

See Common Sections for details.

Performance and scale

• Startup uses a lightweight index, and detailed information is loaded as needed.
• For large systems, prefer splitting diagrams into multiple files instead of putting everything into one diagram.

License

Model Weave is released under the MIT License.