Architecture as Code: реализуем подход Саймона Брауна

Если вы знакомы с подходом к документированию, предложенным Саймоном Брауном, вы могли заинтересоваться им, но, возможно, задавались вопросом о его реализации. Этот репозиторий заполняет пробел, представляя конкретный шаблон реализации подхода, который состоящего из:

1. Модели архитектуры программного обеспечения как код, построенные с использованием Structurizr Lite
2. Документация, созданная с помощью шаблона Arc42
3. Журнал решений, созданный с помощью ADR Tools

Предполагается хранение этой документации в репозитории и работа с ней так же, как и с кодом.

Для чего можно использовать этот шаблон?

• Предпродажа
• Исследование проекта
• Документ по архитектурному решению (SAD)
• Постоянная документация архитектуры вашей системы

Как запустить

• docker compose up -d
• Откройте веб-браузер и перейдите по адресу http://localhost:8081/

Как использовать Structurizr Lite

• http://localhost:8081/workspace/diagrams — диаграммы
• http://localhost:8081/workspace/documentation/Internet%20Banking%20System — документация
• http://localhost:8081/workspace/decisions/Internet%20Banking%20System — ADR
• Справочник по языку
• Руководство по началу работы с Structurizr Lite
• Посмотрите два доклада в нижней части FAQ по C4
• Документы Arc42 находятся в internet-banking-system/docs
• ADR находятся в internet-banking-system/adrs

Что внутри?

1. Модели архитектуры программного обеспечения как код

Structurizr основывается на идее "диаграммы как код", позволяя создавать несколько диаграмм архитектуры программного обеспечения из единой модели.

Существует ряд инструментов для создания совместимых рабочих областей Structurizr, среди которых Structurizr DSL рекомендуется большинству команд.

В примере DSL ниже создаются две диаграммы на основе единого набора элементов и отношений.

model {
    user = person "User"
    softwareSystem = softwareSystem "Software System" {
        webapp = container "Web Application" {
            user -> this "Uses"
        }
        container "Database" {
            webapp -> this "Reads from and writes to"
        }
    }
}

views {
    systemContext softwareSystem {
        include *
        autolayout lr
    }

    container softwareSystem {
        include *
        autolayout lr
    }

    theme default
}

2. Документация

Каждый архитектурный документ в этом репозитории создан с использованием шаблона Arc42 и хранится в формате asciidoc, что позволяет легко отслеживать изменения и внедрять улучшения документации.

3. Журнал решений

Журнал решений создан с помощью ADR Tools, позволяя вести запись каждого архитектурного решения, принятого в проекте, в формате markdown.

Счастливого документирования 📚