Architecture model toolkit

This is a template repo for architecture modelling with a heavy focus on the very basic set-up, decisions, and the tooling to support it.

Current tooling is heavily based on Structurizr and is basically a compilation of different tools.

Here's the description of the setup:

Dev Containers is the tool of choice for interacting with workspace. Shell scripts in the bin directory facilitate and unify interactions.

Structurizr for previewing, editing, validating, and exporting workspaces. The CLI and Lite have been unified into a single tool. Run ./bin/local to start the local web server, or use ./bin/structurizr to access all CLI commands directly.

structurizr-ruby for JRuby scripting and interactive REPL for querying workspace. Run ./bin/repl to open a REPL session

GitHub Actions for automated deploys.

GitHub Codespaces for editing on the go.

There are a few custom QoL plugins in plugins/. See the docs:

• Embed Views Extractor — lets you define views in Markdown and embed them inline, e.g.:

```structurizr{embed:Context}
systemContext system "Context" "Shows the system context" {
    include *
    autoLayout lr
}

## Installation

1. Install [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) for VS Code
2. Open the repository in VS Code and click "Reopen in Container" when prompted
3. That's it!

## Running Structurizr

The template incorporates the unified Structurizr tooling (CLI and Lite have been consolidated into a single tool). Here are the available commands:

* `./bin/structurizr` – run Structurizr CLI directly with any command
* `./bin/local` – start the local web server for viewing and editing diagrams
* `./bin/playground` – start the Structurizr playground for experimenting with DSL
* `./bin/validate` – validate the workspace for syntax errors
* `./bin/inspect` – check the workspace for violations
* `./bin/export` – export the workspace to various formats (e.g., `./bin/export -f png`)
* `./bin/push` – push the workspace to a Structurizr instance

## GitHub actions

The template comes with a GitHub action to push the workspace to a Structurizr on-premises instance. By default, it launches on `workflow_dispatch`, meaning you need to run it automatically from `Actions` tab of your repo. 

However, if you'd like to run it automatically on each push to `main`, feel free to edit `.github/workflows/deploy_workspace.yml` and uncomment the following lines:

```yaml
  # push:
  #   branches:
  #     - main

That'll make it work for each push to the repo.

If you'd like to use GitHub actions, you'll need to configure environment first. See next section.

Pushing workspace to Structurizr instance

If you have a Structurizr workspace on an on-premises installation, you'd probably want to upload your local workspace every now and then.

There are two ways to do so:

• ./bin/push through Structurizr CLI
• GitHub Actions

Both of these options require credentials. For the sake of uniformity, all the tooling assumes the same variable names everywhere

• STRUCTURIZR_WORKSPACE_ID — workspace ID, what you'd put under -id ... in CLI
• STRUCTURIZR_WORKSPACE_KEY — workspace key, -key ...
• STRUCTURIZR_WORKSPACE_SECRET — workspace secret, -secret ...
• STRUCTURIZR_URL — structurizr instance URL, -url https:/..

If you'd like to have any of those features enabled, you need to supply ENV accordingly. The DevContainer is configured to automatically inherit these environment variables from your host system. You can also use .devcontainer/devcontainer.env file to supply those.

If you'd like to use ./bin/push, make sure these environment variables are set before starting the DevContainer.

Conventions

The main expectation is that you'd use this repo as a template for your workspaces and models. Feel free to fork and modify this repo to fit your own needs.

Right now the most sigificant parts of the model look like this:

.
├── docs
│   └── 01-test.md
│   ├── .keep
├── output
│   ├── .keep
├── workspace.dsl
└── workspace.json

Basically, what we've got are:

1. Workspace files -- both DSL and JSON files. DSL is supposed to be authored by us, while JSON is supposed to be generated by Structurizr.
2. docs directory for documentation. It contains an example of embedding diagrams.
3. output directory for all of the CLI-generated outputs. It's gitignored, so feel free to put anything there

License and considerations

This code is licensed under the MIT license.

However, this repository distributes and incorporates other people's works.

arc42

This repository contains a derivative of arc42 8.0 at docs/arc42

Modifications:

• Removed images, config and root file
• src directory is now arc42

This content is licensed under Creative Commons Attribution-ShareAlike 4.0 International License.

JRuby docker image

Dockerfile contains code from JRuby's official Docker image. It is licensed under MIT. You can see the copyright at JRuby Docker repo.