Loading complex structurizr workspace.dsl from partials with preprocessor?

mcbeelen commented 4 months ago

Being a huge fan of the Antora, the c4-model, Structurizr and Kroki I'm currently trying to figure out how to put this all together.

Since Kroki has added support for Structurizr I think there are option. The example all show

Currently I'm working on documenting a system in migration from a monolith towards various microservices. We would like to use features from the Structurizr DSL to include details from the microservices into the workspace.

I envision having the workspace.dsl inside the partials directory of my Antora module, and have that include various other files. In my pages I would like to include diagrams by the key of the view, while referencing the same workspace.

In this issue I would like to explore, discuss and help with working towards a complete solution.

Current situation

An Kroki examples for structurizr shows the entire DSL inside the adoc
The Structurizr Service of Kroki currently handles the parsing over the DSL.
The Asciidoctor Kroki Extension currently preprocesses plantuml and vega diagrams before the are posted to the Kroki-server

Potential solutions

Preprocess the DSL to a workspace.json (using the [https://github.com/structurizr/cli/blob/master/src/main/java/com/structurizr/cli/export/JsonWorkspaceExporter.java](JsonWorkspaceExporter of the Structurizr CLI) and then have the Kroki and the Asciidoc kroki extension have support for a 'new diagram type': structurizr-json.

We might be able to preprocess the structurizr workspace.dsl in the extension as well to generate a workspace.json or I could incorportate the Structurizr CLI in my build pipeline to generate the json first.

Local development and layout.

I'm trying to figure out how to do local previews and manual layout, but running StructurizrLite locally might be suitable for that.

End result

The ideal end result would be similar to functionality currently provided by avisi-cloud structurizr-site-generatr: Based upon Structurizr DSL and .adoc-file generate a static site to publish including support for all other kinds of diagrams like PlantUML and Mermaid.

I'm hoping @ggrossetie is willing to share his thoughts on this.

jrauschenbusch commented 3 months ago

I get your point and i also searched for a solution here.

My way was to put the DSL file in the examples folder of Antora. Maybe partials folder will also work out.

structurizr::example$system.dsl[renderer="mermaid",view-key="Containers"]

Please be aware of the Kroki-hack in the attributes list of the structurizr element. view-key is required by the Kroki server. In the AsciiDoctor diagram documentation it's just named view. Without changing this, in my case the rendered view was determined randomly by Kroki. Not what you want to have of course.

NOTE: For my really huge Structrizr model i needed to configure Kroki to allow much longer URLs. Of course with the common public Kroki server this is not possible.

Here's my configuration for local tests:

version: "3"
services:
  kroki:
    image: yuzutech/kroki
    depends_on:
      - mermaid
      - bpmn
      - excalidraw
    environment:
      - KROKI_MERMAID_HOST=mermaid
      - KROKI_BPMN_HOST=bpmn
      - KROKI_EXCALIDRAW_HOST=excalidraw
      - KROKI_MAX_URI_LENGTH=64000
    ports:
      - "8000:8000"
  mermaid:
    image: yuzutech/kroki-mermaid
    expose:
      - "8002"
  bpmn:
    image: yuzutech/kroki-bpmn
    expose:
      - "8003"
  excalidraw:
    image: yuzutech/kroki-excalidraw
    expose:
      - "8004"

ggrossetie commented 2 months ago

Thanks for sharing this tips @jrauschenbusch. Does this solution work for you?

I envision having the workspace.dsl inside the partials directory of my Antora module, and have that include various other files. In my pages I would like to include diagrams by the key of the view, while referencing the same workspace. In this issue I would like to explore, discuss and help with working towards a complete solution.

Are you referring to the !include directive in Structurizr https://docs.structurizr.com/dsl/includes? If so, we could implement a similar preprocessing task for Structurizr (similar to what we are doing for PlantUML). Having said that, we will need to reimplement the parsing logic since we cannot (or don't want) to add a dependency on Java (this extension is written in Node and Ruby).

jrauschenbusch commented 2 months ago

I think support for Structurizrs !include directive would be awesome for larger Structurizr workspaces or for re-use between Structurizr workspaces.

asciidoctor / asciidoctor-kroki