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:
  • Explore the system interactions
  • Explore the container (application) interactions
  • Explore how people use systems
• 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 plantuml and wget to be installed (e.g. with brew install plantuml wget)

script/generate_images.sh

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