Structurizr instructions for beginners

I would like to share with you instructions on how to describe system architecture as code. The formation of diagrams will be in C4 notation, you can read about the notation itself at the link https://habr.com/ru/articles/778726/.

We will use the Structurizr tool. We will not consider how to introduce a tool into the contour of your landscape, the task is to show what exactly an architect needs to do to describe the current and future state of the system.

Providing an architect's workplace

• Install Java 17+

• Install idea (I use vs code)

• Install the C4 DSL Extension plugin

• Download structurizr-lite.war (source https://docs.structurizr.com/lite/installation)

Create a repository and add a dev branch to it, we will store our architecture in it 🙂

Now everything is ready, let's move on to filling out the project

Filling out the workspace.dsl file

workspace {
    name "наименование системы" 
    description "описание системы, понятноен психечески здоровым людям"
    model {
        # Подключаем ландшафт - справочник систем
        !include landscape.dsl 
        # Подключаем контекстную диаграмму
        !include context.dsl
        # Подключаем контейнерную диаграмму
        !include container.dsl
    }
    views {
        # подключаем стили
        !include styles.dsl 
        systemContext SRTUCTURIZR {
            title "Контекст на сейчас"
            include *
            # авто форматирование, есть разные настройки, можно посмотреть в документации
            autoLayout lr
            exclude relationship.tag!=ASIS
        }
        systemContext SRTUCTURIZR {
            title "Контекст на 2025"
            include *
            # autoLayout lr
            exclude relationship.tag!=Q25
        }
        container SRTUCTURIZR {
            title "Контейнеры"
            include *
            autoLayout lr
            # exclude relationship.tag!=Q25 
        }
    }
}

Filling out the context.dsl file

# Можно для наглядности добавить пользователя
Architector = person "Архитектор" 
softwareSystem SRTUCTURIZR {
# Системный контекст на сейчас
Architector -> SPARXEA "Ведение архитектуры" "Ручной ввод" "ASIS"
SPARXEA -> SRTUCTURIZR "Выгрузка данных по системам ит ландшафта" "Ручной ввод" "ASIS,sync"
# Системный контекст на 2025 год
Architector -> SRTUCTURIZR "Ведение архитектуры" "Архитектура как код" "ASIS,Q25"
SRTUCTURIZR -> SPARXEA "выгрузка результатов" "dsl" "Q25"
}

Filling out the container.dsl file

!element SRTUCTURIZR {
    webapp = container "Веб приложение" {
    }
    database = container "База данных" {
    }
}
# Можно добавить связи
webapp -> database "save" "API" "ASIS

Filling out the landscape.dsl file

# Справочник систем
SRTUCTURIZR = softwareSystem  "Structurizr" "Система для ведения архитектуры как кода" 
SPARXEA = softwareSystem "SPARX EA" "Позволяет вести описания и проектирования систем"

Filling out the styles.dsl file

styles {
            element "Element" {
                background #1168bd
                color #ffffff
                shape RoundedBox
            }
            element "Person" {
                background #1168bd
                color #ffffff
                shape person
            }
            relationship "sync" {
                color #000000
                dashed false
            }
            element "Container" {
                color #ffffff
                shape Pipe
            }   
}

Next you need to run the project using the command via the command line (you can do some *.cmd), the code is listed below

 java "-Djdk.util.jar.enableMultiRelease=false" -jar C:\structurizr-lite\structurizr-lite.war "C:\Users\.git\structurizr"

Where

"-Djdk.util.jar.enableMultiRelease=false"
# атрибут манифеста «Multi-Release» https://habr.com/ru/companies/haulmont/articles/428868/ 
"-jar C:\structurizr-lite\structurizr-lite.war"
# указывается источник structurizr
"C:\Users\.git\structurizr"
# указываем локальный репозиторий 

After launch, go to the browser and contact http://localhost:8080

The description has been generated and is displayed

Hidden text

For clarity, in the above example there are 2 display options, the first option is generated by the system, a line of code is responsible for this

autoLayout lr

The documentation shows different options, you can experiment 🙂

We enter our data on the system context, system containers, you can play with styles (everything is described in detail in the documentation), push it to the repository, profit. Now the architecture is in code form

I kindly ask you to follow the rules of C4 notation and, if necessary, refer to the documentation. A hybrid in the form of a picture is a good thing, but not always clear to everyone

If the approach receives approval within the company, then it will be necessary to collect the system architecture and publish it in structurizr. Structurizr CLI (https://docs.structurizr.com/cli) will help with this. In fact, you need 3 keys and a url

-id: The workspace ID (required)
-key: The workspace API key (required)
-secret: The workspace API secret (required)
-url: The Structurizr API URL (optional; defaults to https://api.structurizr.com)

I hope you at least try this approach and decide for yourself whether it is useful for you or not.

Materials:

https://docs.structurizr.com/ – website with documentation

https://github.com/structurizr/onpremises/releases – here you can download the latest version of structurizr

https://gitflic.ru/project/trifonov-ks/structurizr – an example project just in case

All the best!