FlowConsole .fc.ts DSL (Preview)

FlowConsole по умолчанию ищет файлы, имя которых соответствует шаблону .fc.<ext>, например .fc.ts, и рассматривает их как файлы архитектурной модели. arch/eshop.fc.ts — один из таких файлов: в нём целевая архитектура системы описывается исходным кодом в C4-like нотации, а не в отдельном формате диаграммы.

В текущем Preview основной способ описания модели — runtime DSL, используемый в примере eShop: сущности задаются типизированными object literal-объектами, а взаимодействия описываются fluent-методами потока.

В этой документации публичный пример выступает источником истины:

• репозиторий v-flowconsole-tech/eshop
• файл модели arch/eshop.fc.ts

Что покрывает эта документация

Эта документация специально сфокусирована на текущем Preview runtime DSL в .fc.ts:

• шаблон файлов .fc.<ext>, который FlowConsole по умолчанию трактует как архитектурную модель
• типизированные object literal-сущности: User, ComputerSystem, ReactApp, RestApi
• иерархия через system и belongsTo
• описание потоков через sendsRequestTo, then, getDataFrom, executesRequest и inParallel
• семантика связи через ConnectionOptions.kind

Анатомия модели eShop

Пример eShop организован как простой top-down файл:

const customer: User = { name: "Customer", description: "Online shopper" };
const admin: User = { name: "Store Admin", description: "Manages catalog and orders" };
 
const eshop: ComputerSystem = { name: "eShop Platform" };
const frontend: Container = { name: "Frontends", system: eshop };
const gateway: Container = { name: "API Gateway", system: eshop };
const services: Container = { name: "Backend Services", system: eshop };
const data: Container = { name: "Data Stores", system: eshop };
const messaging: Container = { name: "Event Bus", system: eshop };

Сначала файл задаёт акторов и верхнеуровневые границы системы. Затем под этими границами описываются конкретные приложения, API, хранилища, воркеры и внешние интеграции. Задача такого файла — зафиксировать планируемую архитектурную модель в репозитории, чтобы её можно было версионировать, ревьюить и загружать в FlowConsole.

Как FlowConsole читает .fc.ts как модель

FlowConsole извлекает архитектурную структуру прямо из файла:

1. Типизированные объявления создают узлы.
2. system и belongsTo создают вложенность и контейнерные границы.
3. Flow-методы создают связи и упорядоченные шаги потока.
4. inParallel сохраняет параллельные ветки внутри одного пользовательского сценария.
5. ConnectionOptions.kind меняет семантику связи: синхронный вызов, асинхронная работа, публикация события или зависимость.

То есть файл — это не исходник диаграммы. Это читаемая, версионируемая архитектурная модель целевой системы, которую FlowConsole затем может визуализировать, публиковать и сравнивать с реальностью.

Пример потока

Checkout-сценарий в eShop хорошо показывает основной стиль взаимодействий:

customer.sendsRequestTo(webApp, "checkout")
  .then(webApp).sendsRequestTo(apiGw, "POST /orders")
  .sendsRequestTo(orderingApi, "create order")
  .inParallel(
    () => orderingApi.sendsRequestTo(orderingDb, "INSERT order", { kind: "dependency" }),
    () => orderingApi.sendsRequestTo(orderEvents, "publish OrderCreated", { kind: "event" }),
    () => orderingApi.sendsRequestTo(basketApi, "clear cart")
  );

Один такой блок уже описывает:

• актор, который запускает взаимодействие
• путь запроса через UI и API
• запись в базу данных
• публикацию события
• побочный эффект в другом сервисе

Следующие шаги

• Откройте справочник API, чтобы увидеть точные типы сущностей, поля и flow-методы.
• Откройте руководство по eShop, чтобы пройти полный walkthrough с плейсхолдерами под скриншоты из продукта.