DToS Solution Architecture Repository

Introduction

This repository contains two main components:

1. Solution Architecture Model: Using the DSL Structurizr for generating architecture diagrams
2. Event Catalog: A documentation tool for managing and documenting events in the system

The architecture diagrams generated by Structurizr are referenced within Confluence for the wider team to access.

Repository Structure

• /structurizr: Contains the solution architecture model and related files
• /eventcatalog/nhse-screening-eventcatalog: Contains the Event Catalog application for documenting system events

Getting Started

1. Solution Architecture Model (Structurizr)

To work with the solution architecture model, you'll need to run Structurizr Lite locally. This requires Docker installation.

Prerequisites

• Docker installed from https://www.docker.com/get-started/

Running Structurizr

First, pull the latest Structurizr lite image:

docker pull structurizr/lite

Then run the container (commands vary by operating system):

MacOS and Linux

cd structurizr
docker run -it --rm -p 8080:8080 -v ./:/usr/local/structurizr structurizr/lite

Note: For MacOS Sequoia 15.2 and later, use this command instead to avoid sigterm exceptions:

cd structurizr
docker run --rm -e JAVA_TOOL_OPTIONS="-XX:UseSVE=0" -p 8080:8080 -v ./:/usr/local/structurizr structurizr/lite

Windows

cd structurizr
docker run -it --rm -p 8080:8080 -v %cd%:/usr/local/structurizr structurizr/lite

Once running, access the live view at http://localhost:8080

Make changes to the model

Work has been carried out to try and break out the component services into separate folders to improve the maintainability of the files. The large workspace.dsl was becoming unmanageable.

Each product now has it's own folder. Within which there are 3 files (model, view, relationships). Additionally there is a docs folder which a base markdown file.

It should be possible to isolate changes so there are fewer changes to the main workspace.dsl.

Relationships

Because of the hierarchical nature of the dsl file, relationships become problematic. As a convention, the relationships within the sub folders should only contain 2 types of relationship

• Where the product initiates a request to another service
• Where a User or Staff member interacts with the product

2. Event Catalog

The Event Catalog is located in the /eventcatalog/nhse-screening-catalog directory and contains documentation for system events. Each event is documented with its schema and related information.

Prerequisites

• Node.js (v14 or higher)
• npm (v6 or higher)

Installation

1. Navigate to the eventcatalog directory:

cd eventcatalog/nhse-screening-catalog

2. Install dependencies:

npm install

Running the Event Catalog

1. Start the development server:

npm run dev

2. Open your browser and navigate to http://localhost:3000

The Event Catalog will show all documented events in the system, organized by domain. You can:

• Browse events by domain
• View event schemas
• Search for specific events
• View event relationships and dependencies

Making Changes

Architecture Model Changes

The architecture model is defined in the workspace.dsl file using a domain-specific language. Reference documentation can be found at https://docs.structurizr.com/dsl/language.

The workspace.dsl has been broken down and now makes extensive use of includes. Each 'product' now has its own sub directory, within which there are 3 files:

• *_model.dsl - should contain the model definitions for a product
• *_rels.dsl - should contain the relationships relevant to a specific product
• *_views.dsl - should contain the views appropriate to a specific product

Additionally there is now a docs folder in the product folders. These can be added to with necessary documentation and will be published with the diagrams at the same time.

The model follows a hierarchy:

• SystemContext (top-level)
• Containers
• Components
• Code

Best practices:

• Always document down to the Container level
• Document to Component level only when necessary
• Make changes on a branch and create a Pull Request
• DO NOT merge directly into main
• Managing relationships can be challenging. Therefore as a rule, specify relationships within a product where that product is the initiator of an interaction. For external system relationships, specify and reference them in the main workspace.dsl

Event Catalog Changes

How to make changes to the eventcatalog is covered very explicitly in the docuemntation provided by eventcatalog itself. This can be found here - https://www.eventcatalog.dev/docs/guides

Development Workflow

1. Create a new branch for your changes
2. Make your modifications
3. Create a Pull Request
4. Wait for review and approval
5. Merge only after approval

Remember: Never merge directly into the main branch. All changes must go through the Pull Request process.

Publishing

The contents of the C4 and Eventcatalog once merged into Main will now get published to this site - https://nhsdigital.github.io/dtos-solution-architecture through the deploy-eventcatalog.yml github action. It does this by running two separate tasks: -

• It executes npm run build in the eventcatalog folder to generate the contents for the eventcatalog
• It then execute ghcr.io/nhsdigital/dtos-structurizr-site-generatr generate-site which uses this site's docker image to produce an NHS themed static website
• The two sets of files are zipped up and deployed using github pages for the repository.