hmpps-architecture-as-code

Modelling architecture in HM Prisons and Probations Service (HMPPS) with the C4 model and Structurizr.

Key outputs

Holistic representation of all software systems and containers (applications or data stores) within HMPPS Digital
Applications annotated with API documentation links are published to the Published APIs page
Interactive graph of model elements and their relationships:
Views defined in the model are published to the Diagrams page
- For example, overview of systems with legend
- Published diagram images can be embedded in Confluence or GitHub readmes
- The diagrams will automatically update when they're next changed
Views defined in the model can be generated locally (see below)

Workspaces

This repository defines a Structurizr workspace for the HM Prison and Probation Service.

For the model and diagrams, please visit https://structurizr.com/share/56937.

Linking from other repositories

To link to a live version of a diagram, insert the following code into your repository's readme:

(Replace nomiscontainer with the diagram key in the code)

[Container diagram source](https://github.com/ministryofjustice/hmpps-architecture-as-code/search?q=nomiscontainer)

![Container diagram](https://static.structurizr.com/workspace/56937/diagrams/nomiscontainer.png)

![Container diagram legend](https://static.structurizr.com/workspace/56937/diagrams/nomiscontainer-key.png)

Running

The project is built with gradle.

Action	Command
Build the project	`./gradlew build`
Create a local Structurizr workspace JSON file	`./gradlew run`
Push to the remote Structurizr workspace	`./gradlew run --args='--push'` (please see "Secrets" section below)

🚨 Remote-only changes will be lost

The remote workspace's content is replaced with the content in this repository. Remote-only changes will be lost.

Secrets

The --push command can be configured with these environment variables:

Environment variable	Meaning
`STRUCTURIZR_API_KEY`	Required The API key for the Structurizr API.
`STRUCTURIZR_API_SECRET`	Required The API secret for the Structurizr API.
`STRUCTURIZR_WORKSPACE_ID`	Overrides the default workspace ID.

Example:

STRUCTURIZR_WORKSPACE_ID=12345 \
  STRUCTURIZR_API_KEY=key \
  STRUCTURIZR_API_SECRET=secret \
  ./gradlew run --args='--push'

You can view these secrets on the dashboard, after clicking Show more... next to the desired workspace.

Generating images locally

Requires graphviz and wget to be installed (e.g. with brew install graphviz wget)

script/generate_images.sh

This command will locally generate all defined workspace diagrams without using the Structurizr web API.