Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs(examples): add structurizr export walkthrough (#1176)

Felix-Ayush5ca428f538d8
diff --git a/examples/README.md b/examples/README.md
index 788a93881..991160310 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -12,6 +12,7 @@ self-contained README under `examples/<name>/`.
| [health-coverage/](health-coverage/) | Code health, coverage ingest, and impacted-tests (no LLM key) |
| [opencode/](opencode/) | OpenCode as the LLM provider for wiki generation |
| [security-scan/](security-scan/) | Working-tree security signals + OSS `security scan --history` (no LLM key) |
+| [structurizr-export/](structurizr-export/) | `export --format structurizr` fragment vs standalone (no LLM key) |
## Conventions
@@ -29,4 +30,5 @@ self-contained README under `examples/<name>/`.
- [Code health](../docs/layers/CODE_HEALTH.md)
- [Test intelligence](../docs/layers/TEST_INTELLIGENCE.md)
- [Distill](../docs/agent/DISTILL.md)
+- [Structurizr export](../docs/architecture/structurizr-export.md)
- [CLI: security](../docs/reference/CLI_REFERENCE.md)
diff --git a/examples/structurizr-export/README.md b/examples/structurizr-export/README.md
new file mode 100644
index 000000000..8e43aa07c
--- /dev/null
+++ b/examples/structurizr-export/README.md
@@ -0,0 +1,78 @@
+# Structurizr Export Example
+
+Emit your architecture as [Structurizr](https://structurizr.com) DSL from the
+graph Repowise already built. Deterministic — no LLM key, works after
+`init --index-only`.
+
+## Prerequisites
+
+1. A git repository you can index locally.
+2. `repowise` on `PATH` (`uv tool install repowise` or from this repo:
+ `uv sync --all-packages`).
+3. Index once (graph only is enough):
+
+```bash
+cd /path/to/your-repo
+repowise init --index-only --yes
+```
+
+## 1. Model fragment (default)
+
+Writes a `model { … }` fragment you `!include` from your own `workspace.dsl`:
+
+```bash
+repowise export --format structurizr
+# → typically .repowise/export/repowise-model.dsl (or path from --output)
+```
+
+Include it **inside** your workspace block:
+
+```dsl
+workspace "your name" {
+ !include repowise-model.dsl
+
+ views {
+ systemContext sys_yourrepo {
+ include *
+ autolayout lr
+ }
+ }
+}
+```
+
+Re-export as often as you like — the fragment regenerates; your views/styles stay yours.
+
+## 2. Standalone workspace (no existing workspace.dsl)
+
+When you do not already keep a hand-written workspace:
+
+```bash
+repowise export --format structurizr --standalone -o arch/
+```
+
+`--standalone` refuses to overwrite a `workspace.dsl` it did not write unless
+you pass `--force`. Prefer the fragment once you own the presentation file.
+
+## 3. Optional shaping flags
+
+```bash
+# One box per directory (component level)
+repowise export --format structurizr --standalone --components
+
+# Omit third-party / external systems
+repowise export --format structurizr --no-externals
+```
+
+## Smoke checklist
+
+| Step | Expected |
+|------|----------|
+| `repowise init --index-only --yes` | Completes without an API key |
+| `repowise export --format structurizr` | Writes a `.dsl` fragment; prints include hint |
+| `repowise export --format structurizr --standalone -o /tmp/rw-arch/` | Complete workspace that Structurizr can open alone |
+| Zero containers in the printed counts | Index/graph problem — re-run init, not a format bug |
+
+## Related docs
+
+- [Structurizr DSL export](../../docs/architecture/structurizr-export.md)
+- [CLI: export](../../docs/reference/CLI_REFERENCE.md)