|
1 | 1 | logseq-entity:: [[Logseq/Entity/software-project]] |
2 | 2 | tags:: [[Software/Library]] |
3 | 3 | see-also:: [[diagrams]], [[D2]], [[Diagram/Mermaid]] |
4 | | -- # [Structurizr DSL](https://docs.structurizr.com/dsl) |
5 | | - - **Architecture-as-code** aligned with the **C4 model**: multiple derived views, groups, **styles**, **themes**, and element-level icons; intentionally **not UML**, with a constrained **box-centric** visual notation. |
6 | | - - Strong when the goal is **rigorous software architecture modeling** and consistent views; a weaker match than [[diagrams]] or [[D2]] for a **rich vendor/service-icon** “architecture board” look. |
| 4 | + |
| 5 | +- # [Structurizr](https://structurizr.com/) |
| 6 | + - **Architecture-as-code** toolkit aligned with **[[C4]]**: define architecture in a **[Structurizr DSL](https://docs.structurizr.com/dsl)** workspace and derive multiple consistent views (system context, container, component, deployment, etc.). |
| 7 | + - Intentionally **not [[UML]]**; constrained **box-centric** notation with **styles**, **themes**, groups, and element-level icons—suited to **rigorous software architecture modeling** rather than a rich vendor-icon “architecture board” look (compare [[diagrams]], [[D2]], [[Diagram/Mermaid]]). |
| 8 | + - ## Core idea |
| 9 | + - **Precise, maintainable** architecture models; **reproducible diagrams** from source; fits **developer workflows** (repos, CI/CD). |
| 10 | + - ## Mental model |
| 11 | + - Think in **three layers**—same underlying model, different surfaces: |
| 12 | + - ### 1. Core engine (free, open source) |
| 13 | + - DSL **parser**, **validation**, **diagram generation**, **export** (PlantUML, Mermaid, PNG/SVG, static site). |
| 14 | + - **Local-first**: usable **without** any server; the engine is the center of gravity. |
| 15 | + - ### 2. Delivery modes (interfaces over the engine) |
| 16 | + - **CLI-style**: `export`, `validate`, etc. |
| 17 | + - **Local viewer** (`local`): lightweight **local web UI**. |
| 18 | + - **Static export**: pure **HTML/JS** output. |
| 19 | + - **Server** (`server`): multi-user **workspace** hosting (see licensing). |
| 20 | + - **vNext direction**: tooling consolidated toward a **single binary / Docker image**—you pick a **command mode** (`local`, `server`, `export`, …) rather than a separate “product” name. |
| 21 | + - ### 3. Structurizr server (optional, commercialized) |
| 22 | + - **Workspace storage**, **collaboration**, **auth**, **APIs**. |
| 23 | + - Prebuilt **server** binaries are **licensed**; the **core** modeling/export path stays **free** without it. |
| 24 | + - ## Free workflows (no server, no license) |
| 25 | + - You do **not** need a server, a license, or a hosted UI to use the **core** toolchain. |
| 26 | + - ### A. Diagrams only |
| 27 | + - ~~~ |
| 28 | + export -workspace workspace.dsl -format plantuml |
| 29 | + ~~~ |
| 30 | + - Or raster output, e.g.: |
| 31 | + - ~~~ |
| 32 | + export -workspace workspace.dsl -format png |
| 33 | + ~~~ |
| 34 | + - ### B. Static site |
| 35 | + - ~~~ |
| 36 | + export -workspace workspace.dsl -format static -output site |
| 37 | + ~~~ |
| 38 | + - Produces `index.html` plus JS/CSS—**no backend**, **client-side** interactive diagrams; host on GitHub Pages, S3, or any static host. |
| 39 | + - ### C. Optional local UI |
| 40 | + - ~~~ |
| 41 | + local /path/to/workspace |
| 42 | + ~~~ |
| 43 | + - Runs a **local** viewer only when you want it. |
| 44 | + - ## [[Structurizr/export/Static site]] export vs layout |
| 45 | + - Static export supports **zoom/pan**, **view navigation**, **tooltips**, **perspectives**. |
| 46 | + - Does **not** bundle full **documentation** or **ADR** workflows by itself—those live outside or in other tooling. |
| 47 | + - **Layout**: the **DSL** does **not** persist manual layout; **JSON** workspace format **does**. So **auto-layout** can stay DSL-only; **hand-tuned layout** → prefer **JSON** (or a JSON-backed workflow). |
| 48 | + - ## [[Structurizr/MCP/Server]] |
| 49 | + - A **stateless HTTP-oriented wrapper** around Structurizr capabilities for **agents and automation**—**not** the same as the multi-user **Structurizr server**, and **not** a paid component by itself. |
| 50 | + - **Typical**: parse DSL → JSON, **validate**, **export** diagrams (PlantUML, Mermaid), **inspect** models. |
| 51 | + - **Optional**: proxy **CRUD** against a **Structurizr server** (then **server licensing** applies). |
| 52 | + - **Local-only MCP** use → **core engine** only, no license for normal open-source/local paths. |
| 53 | + - ## How the pieces relate |
| 54 | + - ~~~ |
| 55 | + DSL → Core engine → Output |
| 56 | + ↑ |
| 57 | + CLI / Docker / MCP |
| 58 | + |
| 59 | + Optional: |
| 60 | + MCP → Structurizr server (licensed) |
| 61 | + ~~~ |
| 62 | + - ## Typical pipelines |
| 63 | + - **Minimal**: [[DSL]] → export → [[png]] / [[Mermaid]] / [[PlantUML]] |
| 64 | + - **Docs site**: [[DSL]] → export static → [[GitHub/Pages]] (or any static host) |
| 65 | + - **Interactive local**: `DSL → local` |
| 66 | + - **Automation / AI**: `DSL → MCP → pipeline or agent → diagrams` |
| 67 | + - ## Strengths and trade-offs |
| 68 | + - **Strengths**: **C4** rigor, **consistent multi-view** models, **architecture as code**. |
| 69 | + - **Trade-offs**: less **visually free-form** than general diagram languages; weaker fit than some tools for **dense vendor/service icon** boards (again vs [[diagrams]], [[D2]], [[Diagram/Mermaid]]). |
| 70 | + - ## Summary |
| 71 | + - **Core** = **DSL → compiler → diagrams** (free, local-first). |
| 72 | + - **Server** = optional **hosted** collaboration layer (**licensed** where applicable). |
| 73 | + - **MCP** = **programmable** wrapper for integration—not required for everyday use. |
0 commit comments