# Model Weave

日本語版: [README-ja.md](https://github.com/nejimakibird/model-weave/blob/main/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.

## 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](https://github.com/nejimakibird/model-weave/blob/main/docs/getting-started.md) - A 5-minute tutorial.
* [Command Guide](https://github.com/nejimakibird/model-weave/blob/main/docs/commands.md) - Full command and template reference.
* [Format Guide](https://github.com/nejimakibird/model-weave/tree/main/docs/formats) - How to write each model type.
* [Samples](https://github.com/nejimakibird/model-weave/tree/main/samples) - Example models and diagrams.
* [Japanese README](https://github.com/nejimakibird/model-weave/blob/main/README-ja.md) - 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, such as `custom`, `mermaid`, and `mermaid-detail`.
* 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](https://github.com/nejimakibird/model-weave/blob/main/docs/V0.8-rendering-policy.md) for details.

### Main formats

* **Stable**: `class`, `er_entity`, `dfd_diagram`, `data_object`, and others.
* **Evolving**: `screen`, `app_process`, `rule`, `codeset`, and others.

### Installation

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

### Viewer behavior

* Supports zoom, fit, pan, and real-time diagnostics.
* 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.

See [Common Sections](https://github.com/nejimakibird/model-weave/blob/main/docs/formats/FORMAT-common-sections.md) 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.