Решения, компромиссы и риски¶

Ключевые решения¶

Markdown как портативный источник истины¶

Выход LLM и технический выход уже Markdown. Продукт сохраняет Markdown, Mermaid, иконки и обычные ассеты вместо проприетарного формата редактора. Совместимость с Git, VS Code / Cursor, MkDocs и обычным Markdown-тулингом - продуктовое требование, а не запоздалый экспорт.

Client-side-first рендеринг¶

Профессиональные черновики остаются в браузере для рендера, темы, Mermaid, локальных ассетов и PDF. Серверная обработка - явное действие компиляции, а не путь по умолчанию.

Инфраструктура AWS, управляемая Terraform¶

Однопользовательской эксплуатации нужно пересобираемое окружение. Продакшен AWS выражен в Terraform, деплоится через GitHub Actions с OIDC.

Cognito для аутентификации¶

Управляемая идентичность для SaaS вместо собственного JWT-стека. Роли (USER / ADMIN / SUPER_ADMIN) сидят поверх идентичности Cognito.

Кредиты как тарификация compute¶

Единица монетизации - ИИ с переменной стоимостью. Локальный рендеринг не ухудшается, чтобы вынудить оплату. Кредиты ограничивают стоимость на пользователя и на задачу.

Runtime / версионированные промпты¶

Поведение ИИ должно меняться независимо от деплоев приложения. Промпты и связанная конфигурация живут в runtime-конфигурации на DynamoDB с публикацией / откатом.

Универсальный Harness vs логика на каждый Compiler (целевое)¶

Текущие трансформации - реализации на каждый тип артефакта. Цель - универсальная оркестрация, исполняющая контракт Compiler. Добавление Compiler не должно требовать изменения ядра Harness.

Слой обработки vs Cloud Workspace (стратегический разворот)¶

Проприетарное хранение документов и функции workspace снижены в приоритете. DocCompile владеет компиляцией, а не местом, где живут документы.

См. также Architecture Decision Records.

Архитектурные компромиссы¶

1. Markdown как портативный источник истины¶

Контекст¶

LLM и инженеры уже производят Markdown. Проприетарный холст дал бы lock-in и сломал Git-native workflow.

Принятое решение¶

Сохранить GFM / Markdown, Mermaid, иконки, совместимые с Iconify, YAML front matter и обычные ссылки на ассеты как рабочее представление.

Отклонённые альтернативы¶

WYSIWYG-формат в духе Word; блоки в стиле Notion как источник истины.

Обоснование¶

Портативные стандарты снижают стоимость переключения, совпадают с существующими инструментами автора и держат diagrams-as-code в том же файле, что и текст.

Компромиссы¶

Точность печати/PDF сложнее, чем в InDesign или Word.
Пользователи, которым нужен блочный редактор, могут уйти.
Mermaid и краевые случаи пагинации становятся продуктовой работой.

Компенсирующие меры¶

Укрепление пагинации и профессиональные темы на клиенте.
Изоляция сломанной диаграммы от остального документа.
Позднее LaTeX как опция, а не обязательный исходный формат.

Триггер пересмотра¶

Платящий сегмент, который не может принять Markdown как исходник; или печатные ограничения, которые нельзя закрыть в браузере.

2. Client-side-first рендеринг вместо серверного редактора¶

Контекст¶

Черновики включают неопубликованную архитектуру, требования и персональные карьерные данные. Обязательный путь «загрузить, чтобы предпросмотреть» конфликтовал бы с позицией по приватности и повышал бы базовую стоимость.

Принятое решение¶

Браузер рендерит и экспортирует локально. Сервер используется, когда пользователь запрашивает компиляцию, биллинг или административные операции.

Отклонённые альтернативы¶

Серверный pipeline рендеринга как единственный путь; хранение каждого документа в облачном workspace для предпросмотра.

Обоснование¶

Приватность по умолчанию, низкая стоимость простоя и отсутствие базы документов как предпосылки публикации.

Компромиссы¶

Серверные возможности требуют явной загрузки / компиляции.
CPU браузера и print CSS становятся первоклассными ограничениями.
Синхронизация документов между устройствами не является платформенной функцией.

Компенсирующие меры¶

Явная граница UI между локальным экспортом и AI-компиляцией.
Кредиты и идентичность только на серверном пути.
Целевые Git / CLI sinks вместо проприетарного хранилища.

Триггер пересмотра¶

Нужна серверная пагинация Chromium такого качества, которое браузер не даёт; тогда ограниченный Fargate worker, а не бэкенд редактора по умолчанию.

3. AWS, управляемый Terraform, вместо консоли или CDK¶

Контекст¶

Эксплуатации под руководством основателя нужно воспроизводимое окружение и дешёвое восстановление инфраструктуры, а не уникальный snowflake-аккаунт.

Принятое решение¶

Продакшен-топология AWS - Terraform.

Отклонённые альтернативы¶

Click-ops в консоли; AWS CDK; Pulumi.

Обоснование¶

Декларативная инфра совпадает с остальной позицией docs-as-code. Terraform достаточен для этой serverless-топологии.

Компромиссы¶

Состояние Terraform и дисциплина blast-radius - операционные обязанности.
CDK мог бы естественнее ложиться на некоторые AWS API.
Drift всё равно нужно отслеживать.

Компенсирующие меры¶

Apply через GitHub Actions с OIDC.
Least-privilege IAM в той же кодовой базе.
Без долгоживущих ключей деплоя в CI.

Триггер пересмотра¶

Рост команды, которому нужен другой стандарт IaC; или возможности AWS, которые Terraform не выражает чисто.

4. Cognito для аутентификации¶

Контекст¶

SaaS нужны регистрация, сессия и роли без построения собственной платформы идентичности.

Принятое решение¶

Amazon Cognito как провайдер идентичности для аутентифицированных маршрутов.

Отклонённые альтернативы¶

Auth0; собственная выдача JWT; Firebase Auth.

Обоснование¶

Остаётся внутри аккаунта AWS, интегрируется с authorizers API Gateway и избегает ещё одного вендора для небольшого продукта.

Компромиссы¶

UX и квоты Cognito - это AWS.
Ограничения Hosted UI против полностью кастомного логина.
Мультирегиональная идентичность не бесплатна.

Компенсирующие меры¶

RBAC повторно enforced на бэкенде, а не только в токене.
Локальные функции остаются доступны без входа.

Триггер пересмотра¶

Требования к идентичности, которые Cognito не закрывает (сложность enterprise IdP, специфическая упаковка compliance), по цене, оправдывающей Auth0 или выделенный IdP.

5. Кредиты как тарификация compute¶

Контекст¶

Вызовы LLM имеют переменную стоимость. Плата за экспорт PDF обложила бы бесплатный локальный фундамент и пригласила бы худший продукт.

Принятое решение¶

Кредиты тарифицируют AI / compute-тяжёлые операции. Локальное создание и публикация остаются полноценными без кредитов.

Отклонённые альтернативы¶

Только подписка с безлимитным ИИ; цена за PDF; прятание качества рендеринга за paywall.

Обоснование¶

Выравнивает цену с фактической стоимостью провайдера. Сохраняет последнюю милю публикации как заслуживающий доверия бесплатный/локальный путь.

Компромиссы¶

UX кредитов сложнее плоской подписки.
Пользователи могут недоиспользовать ИИ, если пакеты непонятны.
Само по себе не предотвращает проблемы качества.

Компенсирующие меры¶

Учёт стоимости на уровне задачи.
Rate limits и таймауты при сбоях.
Paddle как merchant of record, чтобы не строить налоговую/платёжную машину самостоятельно.

Триггер пересмотра¶

Сегмент, которому нужна только простая подписка на ИИ; или ценообразование провайдера, из-за которого пакеты невозможно объяснить.

6. Runtime / версионированные промпты вместо зашитого поведения ИИ¶

Контекст¶

Качество компиляции будет меняться еженедельно. Передеплоивать SPA или Lambda, чтобы подкрутить промпт, - неверная связка релизов.

Принятое решение¶

Промпты и связанная runtime-конфигурация версионируются на сервере, с публикацией и откатом.

Отклонённые альтернативы¶

Промпты, зашитые в сборки приложения; один глобальный неверсионированный blob промпта.

Обоснование¶

Отделяет релизы поведения модели от релизов приложения. Позволяет INTERNAL-тестирование до PUBLIC.

Компромиссы¶

Runtime-конфиг становится продакшен-поверхностью, которой нужен контроль доступа.
Расхождение промпт/код, если приложение не может исполнить старый контракт.
Операторы могут быстро выкатить плохой промпт.

Компенсирующие меры¶

Только ADMIN / SUPER_ADMIN.
Путь отката.
Целевой жизненный цикл Compiler INTERNAL -> PUBLIC.

Триггер пересмотра¶

Контракты Compiler становятся артефактами, определёнными в коде, а промпты - только параметрами; тогда версионирование конфига и контракта должно оставаться согласованным.

7. Универсальный Harness vs workflow-логика на каждый Compiler (целевое)¶

Контекст¶

Рабочие трансформации существуют как реализации на каждый тип. Это не масштабируется на много Compiler, Situations или Patch Compile.

Принятое решение¶

Эволюционировать к универсальному Harness, который исполняет контракты, поставляемые Compiler. Предпочесть Step Functions для ограниченной многостадийной оркестрации вместо автономного графа агентов.

Отклонённые альтернативы¶

Бессрочно держать жёстко прошитую оркестрацию на каждый Compiler; маршрутизация агентов в стиле LangGraph как значение по умолчанию.

Обоснование¶

Планируемый Harness - ограниченная, сначала детерминированная оркестрация с опциональными семантическими проверками. Фреймворк агентов опционален, только если маршрутизация действительно станет model-driven.

Компромиссы¶

Стоимость миграции с текущих задач на каждый тип.
Операционная сложность Step Functions.
Риск построить фреймворк до того, как 2–3 Compiler действительно хороши.

Компенсирующие меры¶

Начать с небольшого набора эталонных Compiler.
Детерминированные проверки где возможно; явный сбой вместо выдуманного выхода.
LangGraph остаётся поздней опцией, а не текущим целевым ядром.

Триггер пересмотра¶

Маршрутизация становится открытой и model-driven; или Step Functions оказываются плохой посадкой для графа стадий.

8. Слой обработки vs Cloud Workspace¶

Контекст¶

Более ранний путь расширения - проприетарное облачное хранение, workspace и более широкий редактор. Это конкурирует с инструментами, которые у пользователей уже есть.

Принятое решение¶

Снизить приоритет проприетарного хранения документов. Владеть трансформацией. Сохранять в локальные файлы, загрузки, Git, CLI и позднее API.

Отклонённые альтернативы¶

Полноценный workspace в духе Notion как центр продукта.

Обоснование¶

Ниже стоимость переключения, лучше посадка на технические workflow и чище история приватности.

Компромиссы¶

Нет облака документов между устройствами по умолчанию.
Сложнее показать «все ваши документы в DocCompile».
Интеграции становятся важнее внутреннего дерева файлов.

Компенсирующие меры¶

Сильное local/Git-native направление на дорожной карте.
Компиляция как явный ценный момент, а не место, где жить.

Триггер пересмотра¶

B2B-покупатель, который не примет продукт без hosted workspace; тогда workspace был бы интеграцией, а не ядром движка Compiler.

Риски¶

Риск	Почему это важно	Митигирующая мера
Качество трансформации может недостаточно превосходить хороший промпт LLM	Пользователи не заплатят за тонкую обёртку	Сначала эталонные Compiler; контракты и валидаторы, а не театр промптов
Семантическая валидация становится театром валидации	Ложное доверие	Отделить детерминированные проверки от вероятностных; никогда не утверждать «AI verified»
Доменная работа на каждый Compiler плохо масштабируется	Пропускная способность основателя	Небольшой набор Compiler; инварианты Harness; INTERNAL -> PUBLIC
Drift многоартефактных Situations	Противоречивые пакеты	Канонические факты и кросс-артефактные проверки (целевое)
Patch Compile сложен	Brownfield - настоящая работа	Считать более поздней эпохой; зависит от идентичности, фактов, контрактов, diff
Холодный старт eval-датасетов	Нет Compiler Health	Dogfood, outcome signals, локальные корзины edit-distance
Поведение и цены провайдера меняются	Шоки стоимости и качества	Сменяемый LLM; кредиты; версионированные промпты
Техническая аудитория сопротивляется SaaS lock-in	Дистрибуция	Local/Git-native путь; Markdown остаётся портативным
Дистрибуция	Продуктовый риск независимо от архитектуры	Dogfooding, узкие Compiler, явные демо-артефакты