Architecture As Code Tools (aact)

🇷🇺 Русский | 🇬🇧 English

CLI и библиотека для валидации, анализа и генерации архитектуры микросервисных систем, описанной "as Code" (PlantUML C4, Structurizr).

Инструменты для работы с архитектурой в формате "as Code":

1. Код и примеры покрытия тестами микросервисной архитектуры, описанной в plantuml (#)
2. Автогенерация архитектуры (#)
3. Тестирование архитектуры модульного монолита (#)

Планы развития инструментов и репозитория. PullRequest'ы и Issues'ы приветствуются.

Справочник принципов и паттернов проектирования с примерами покрытия их тестами (пополняется...)

Телеграм-канал: Архитектура распределённых систем

aact можно использовать двумя способами: как CLI (npx aact check, авто-фикс, генерация артефактов) или как библиотеку (импортировать aclRule, analyzeArchitecture и пр. в свои тесты на vitest/jest). CLI — ниже, library-режим — в соответствующем разделе.

Quick Start (CLI)

В пустой папке:

# Создаёт aact.config.ts и стартовый architecture.puml с одним
# умышленным нарушением, чтобы было что чинить
npx aact init

# Покажет 1 нарушение CRUD-правила (orders → orders_db напрямую)
npx aact check

# Применит auto-fix: добавит orders_repo как посредника к БД
npx aact check --fix

# Снова чисто
npx aact check

После этого правь architecture.puml под свою систему — синтаксис C4-PlantUML.

Остальные команды

npx aact check --dry-run             # preview auto-fix без записи
npx aact model                       # inspect нормализованной C4-модели
npx aact analyze                     # coupling/cohesion метрики
npx aact view                        # локальный live-workbench в браузере
npx aact generate --format plantuml  # сгенерировать .puml из источника
npx aact generate --format model-json
npx aact generate --format kubernetes
npx aact generate --format compose

--fix пишет правки обратно в source.path. Отдельного source.writePath в v3 нет.

Что создаёт aact init

Два файла рядом:

• aact.config.ts — настройки источника и набор включённых правил. Использует import type { AactConfig } — рантайм-резолва пакета не происходит, поэтому npx aact check работает без npm install aact.
• architecture.puml — стартовая C4-схема с одним сервисом, одной БД и умышленным нарушением CRUD-правила. Замени на свою.

// aact.config.ts (фрагмент)
import type { AactConfig } from "aact";

const config: AactConfig = {
  source: {
    type: "plantuml", // "plantuml" | "structurizr" | "model-json" | "kubernetes" | "compose"
    path: "./architecture.puml",
  },
  rules: {
    acl: true,
    acyclic: true,
    apiGateway: true,
    crud: true,
    dbPerService: true,
    cohesion: true,
    stableDependencies: true,
    commonReuse: true,
  },
};

export default config;

AI-агенты

aact поставляет agent skill (aact-architect) и стабильный JSON-envelope, чтобы AI-агенты (Copilot, Claude, Codex, Cursor, Cline) могли работать с ним без парсинга текста:

# Установить скилл, чтобы агент знал когда вызывать aact
npx aact skill install --claude     # Claude Code
npx aact skill install --codex      # Codex (общий путь ~/.agents/skills)
npx aact skill install --cursor     # Cursor (тот же общий путь)
npx aact skill install --copilot    # GitHub Copilot (тот же общий путь)
npx aact skill install --cline      # Cline
npx aact skill install --all        # все клиенты сразу

# Machine-readable команды (все поддерживают --json)
npx aact model --json    # распарсенная C4-модель + диагностики
npx aact check --json    # violations + suggestedFixes + каталог правил
npx aact check --sarif   # SARIF v2.1.0 для GitHub Code Scanning
npx aact analyze --json  # метрики связности и связанности

Exit codes: 0 чисто, 1 нарушения, 2 tool error. Форма envelope стабильна с schemaVersion: 1 — полный контракт для агентов см. в AGENTS.md.

Использование как библиотеки

import {
  plantumlFormat,
  aclRule,
  acyclicRule,
  crudRule,
  analyzeArchitecture,
  validateModel,
} from "aact";

// Загрузка через format — возвращает Model + diagnostic issues
const { model, issues } = await plantumlFormat.load("architecture.puml");
for (const issue of issues) console.warn(`model:`, issue);

// Проверка правил — uniform signature (model, options?) => Violation[]
const aclViolations = aclRule.check(model);
const cyclicViolations = acyclicRule.check(model);
const crudViolations = crudRule.check(model, { repoTags: ["repo", "dao"] });

// Анализ метрик
const { report } = analyzeArchitecture(model);
console.log(`Elements: ${report.elementsCount}`);

// Прямой доступ к elements / boundaries — Record<name, ...>
for (const element of Object.values(model.elements)) {
  console.log(`${element.kind} ${element.name}`);
}
const ordersService = model.elements["orders"];

Полный API: Model, Format, RuleDefinition. См. CHANGELOG.md для v2 → v3 migration.

Примеры

Запускаемые из коробки (склонируй репо, cd examples/<name>, npx aact check):

• examples/ecommerce-structurizr/ — Structurizr-источник с workspace.json + workspace.dsl, полный цикл правил и auto-fix.
• examples/custom-rules/ — PlantUML-источник + два своих правила (bcIsolation, requireOwnerTag) через defineConfig / defineRule — как писать и подключать кастомные правила.
• examples/violations-demo/ — мини-набор умышленных нарушений по каждому правилу — чтобы посмотреть, как выглядит вывод и какие правки предлагает --fix.

Тестовые сценарии (для разработчиков пакета, запускаются через vitest):

• examples/banking-plantuml/, examples/common-reuse-plantuml/ и examples/microservices-structurizr/ — интеграционные тесты архитектур из fixtures/.

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

• Гайды — практические сценарии: моделирование, CI, custom rules, diff
• Справочник — правила, команды, форматы (генерируется из кода)
• Справочник паттернов — принципы и паттерны с примерами тестов
• ADR — Architecture Decision Records
• Roadmap — планы развития
• AGENTS.md — инструкции для AI-агентов, работающих с aact

Testing

Тестовый стек разделён на четыре уровня:

pnpm test            # все unit + integration + e2e
pnpm test:unit       # только unit
pnpm test:integration # интеграционные на реальных фикстурах
pnpm test:e2e        # subprocess-тесты CLI через execa
pnpm test:coverage   # с v8 coverage + порогами
pnpm test:mutation   # Stryker mutation testing

Метрики качества тестов:

• Coverage (v8): порог в CI — statements ≥95%, branches ≥85%, functions ≥95%, lines ≥95%
• Mutation score (Stryker) ≥95% — каждое смысловое изменение в исходнике должно ломать хотя бы один тест
• Property-based (@fast-check/vitest) на option-bearing правилах — защита от «hardcoded literal where option should be read» бага
• Inline snapshots на генераторах для regression-pin'а формата вывода
• E2E на цепочке init → check → fix → recheck через npx aact в subprocess

Публичные материалы

Раз архитектура — «as Code», почему бы её не покрыть тестами?!

https://www.youtube.com/watch?v=POIbWZh68Cg       https://www.youtube.com/watch?v=tZ-FQeObSjY

Статья на Хабре

Автогенерация архитектуры

https://www.youtube.com/watch?v=fb2UjqjHGUE

Покрытие архитектуры тестами

Что это, какую боль решает, и с чего начать?

Раз архитектура — «as Code», почему бы её не покрыть тестами?!

Тема идеи и данный открытый репозиторий вызвал неожиданную волну позитивных отзывов о попадании в яблочко болей и о применимости и полезности решения :)

Подход помогает решить проблемы неактуальности, декларативности и отсутствия контроля ИТ-архитектур и инфраструктуры (ограничение и требование — архитектура и инфраструктура должны быть "as code").

Тесты проверяют 2 больших блока:

• актуальность архитектуры реальному работающему в продакшне решению
• соответствие "нарисованной" архитектуры выбранным принципам и паттернам проектирования

Подробнее о подходе, решаемых проблемах, схеме работы представленного в репозитории примера и проверяемых в тестах репозитория принципах — на слайдах.

Схема работы

Визуализация примера автоматически проверяемого принципа (отсутствие бизнес-логики в CRUD-сервисах)

Пример архитектуры, которую покроем тестами

Пример тестов

1. find diff in configs and uml containers — проверяет актуальность списка микросервисов на архитектуре и в конфигурации инфраструктуры
2. find diff in configs and uml dependencies — проверяет актуальность зависимостей (связей) микросервисов на архитектуре и в конфигурации инфраструктуры
3. check that urls and topics from relations exist in config — проверяет соответствие между параметрами связей микросервисов (REST-урлы, топики kafka) на архитектуре и в конфигурации инфраструктуры
4. only acl can depend on external systems — проверяет, что не нарушен выбранный принцип построения интеграций с внешними системами только через ACL (Anti Corruption Layer). Проверяет, что только acl-микросервисы имеют зависимости от внешних систем.
5. connect to external systems only by API Gateway or kafka — проверяет, что все внешние интеграции идут через API Gateway или через kafka

Автогенерация архитектуры

Генерация архитектуры из описанной «as Code» инфраструктуры

Сравнение белковой составленной вручную архитектуры и сгенерированной.

Ручная:

Сгенерированная:

Тестирование модульного монолита

Тестами можно покрывать не только архитектуру микросервисов, но архитектуру монолитов, особенно, если они модульные.

• Тест архитектуры модульного монолита на C#

Тестирование на основе информации из кода

Информацию об архитектуре реализованной системы можно извлечь и из ее кода, особенно, если он написан качественно;)

• Извлечение информации об архитектуры системы из ее кода