Model draft architecture using Structurizr

[mpbrown]

Related Issue

• Resolves Model draft architecture with Structurizr #5

Changes Proposed

• Adds ./docs folder to store architecture documentation
• Adds just arch view as the command to run Structurizr locally

Additional Information

• Model has been streamlined to only show the first iteration of Difference in Docs (i.e. without adding in the additional complexity of jurisdictional users managing custom configurations via UI and backend)

Testing

• Pull down branch and make sure you have Just and Docker both installed
• Run just arch view to start the Structurizr container
• View the architecture in your browser at http://localhost:7268.

Sequence Diagram

Checklist for Primary Reviewer

• Any large-scale changes have been deployed and smoke tested
• Any content updates (user-facing error messages, etc) have been approved by content team
• Any dependencies introduced have been vetted and discussed

[mpbrown]

This file gets generated automatically based on workspace.dsl

[kevinfiol]

This doesn't render the newlines for me, sadly 😢

[mpbrown]

Hmm are there any local terminal settings that would cause it to not render? This is how it appears in my bash terminal and I think I have default settings

[kevinfiol]

Does it render correctly for you when using an external terminal? (As opposed to the integrated VSCode terminal)

I am using Bash w/ the default terminal included on Fedora (Konsole).

EDIT: I believe that echo in Bash will not print newlines by default, whereas printf will.

[mpbrown]

Yeah it renders with both the Terminal app (Powershell window invoking WSL2) and the git bash terminal, but I'm cool with changing it to printf if that has more consistent compatibility

[kevinfiol]

Thoughts on encapsulating the docker options in a compose file, and then having Justfile run docker compose commands? The file can be simple as:

EDIT: could maybe also specify a docker image tag here unless we're OK with always pulling latest

# docs/compose.structurizr.yml
services:
  structurizr:
    image: structurizr/structurizr
    volumes:
      - ./:/usr/local/structurizr
    ports:
      - "7268:8080"
    command: local # default to running the local command, but let docker compose override if necessary

Then in the Justfile:

[doc('Sets up the Structurizr instance locally on port 7268.')]
view:
    @echo "*******************\n\n🌐 View Structurizr in your browser at http://localhost:7268\n\n*******************\n"
    docker compose -f compose.structurizr.yml up structurizr

[doc('Exports diagrams in dot format (GraphViz) into a `diagrams/` directory.')]
render-dot:
  docker compose -f compose.structurizr.yml run --rm structurizr \ # remove container after running command
    export -workspace workspace.json -format dot -output diagrams # override the local command with `export`

[mpbrown]

Tbh I think the extra docker compose file would be somewhat unnecessary since this will only be running as a standalone devtool to view or edit the architecture. The documentation for Structurizr vNext has docker run instructions directly and I think it's clearer for a one-off container like this. Plus, once we introduce multiple services that we'll want to have in a docker-compose file like db, lambda, likely UI and backend later on, then it'll be nice to have just one main docker-compose file

[kevinfiol]

I do think there is value in making the Justfile easier to read, and reduce the duplication of the docker options especially if we eventually want to pin the image tag (compose seems like the idiomatic way to do this). There is also nothing keeping us from having multiple compose files for different purposes down the road.

[mpbrown]

I think adding docker compose for Structurizr would make it feel harder to read because it hides the straight forward docker commands behind an additional layer of abstraction in a separate file. We could certainly have multiple compose files in the future like we had on SimpleReport, but that adds extra abstraction to keep track of in a way that I don't think we necessarily need for Structurizr.

FWIW I think these diagram export commands will realistically be rarely used, but if duplication is a concern what are your thoughts on using Just variables to make sure they all use the same volume binding and image tag structurizr/structurizr:latest so then it's all clearly defined in one file location?

[kevinfiol]

I was mostly referring to the combo of Bash backward slash escapes and CLI flag sequences like -v ./:/usr/local/structurizr. I acknowledge the compose file would add an "extra place to look" when trying to read the Justfile.

FWIW I think these diagram export commands will realistically be rarely used, but if duplication is a concern what are your thoughts on using Just variables to make sure they all use the same volume binding and image tag structurizr/structurizr:latest so then it's all clearly defined in one file location?

It's a decent in-between, but this does move things into Justfile DSL world as opposed to keeping it in Docker. I do think the compose file is the cleanest solution, but I'm OK with the existing solution because as you said, we may not be using these commands or modifying this file much in the future. 👍

[mpbrown]

I'm cool with moving it to a compose file if that more familiar Docker context makes it easier to read compared to docker run with multiple flags. Tbh replacing parts of the commands with Just variables also adds some noise anyway

[kevinfiol]

Looks great so far, I was able to run and view the diagrams and render the mermaid and c4plantuml formats.