DocCompile - демо-сборка

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

Содержание

• Краткое описание
• Обзор
• Роль и обязанности
• Архитектура и интеграции
• Решения, компромиссы и риски
• Дорожная карта и демонстрация

Краткое описание

Статус

Рабочий SaaS с развивающейся продуктовой гипотезой. Реализованный фундамент - издатель в модели docs-as-code и сервис AI-трансформаций. Целевое направление - платформа компиляции профессиональных артефактов.

Роль

Основатель: владелец продукта, системный архитектор и владелец реализации.

Стек

Клиентский SPA; AWS CloudFront, private S3, API Gateway, Lambda, DynamoDB, Cognito; Terraform; GitHub Actions с OIDC; сменяемый LLM-провайдер; биллинг через Paddle.

Точный состав сервисов и детали коммерческого контура следует подтверждать по продуктовому репозиторию.

Ценность проекта

Для целевой аудитории (инженеры, аналитики, архитекторы и другие профессионалы, которые уже работают в Markdown):

• превратить структурированный Markdown, Mermaid и иконки архитектуры в профессиональный PDF, не выходя из docs-as-code workflow;
• по умолчанию держать документ в браузере; отправлять содержимое на сервер только при явном запросе AI-компиляции;
• использовать ограниченные, тарифицируемые кредитами AI-трансформации вместо безграничной чат-генерации.

Для профессионального профиля:

• SaaS под руководством основателя: от продуктового discovery до serverless-архитектуры AWS, идентичности, биллинга и эксплуатации;
• задокументированный разворот от проприетарного workspace к слою обработки;
• контролируемое исполнение LLM: версионированные промпты, задачи трансформации, границы стоимости и целевая модель Artifact Contract / Harness.

Что демонстрирует

Этот проект демонстрирует способность:

• провести продукт от рабочего движка рендеринга до коммерческого AWS SaaS-контура;
• держать архитектуру, стоимость, приватность и поведение ИИ под явным контролем, а не считать LLM самой системой;
• менять продуктовую гипотезу, когда становится ясно, что конкурировать за хранение документов - неверная борьба;
• отделять то, что реализовано сегодня, от направления Compiler / Harness, которое проектируется следующим.

Обзор

DocCompile - платформа компиляции профессиональных артефактов в развитии. Она началась как издатель в модели docs-as-code и движется к слою обработки, который компилирует сырой исходный материал в профессиональные артефакты.

Исходная продуктовая формула:

Markdown
+ Mermaid
+ иконки архитектуры
+ изображения
+ профессиональные темы
-> PDF

Текущая продуктовая формула:

Source in. Contract satisfied. Artifact out.

Развёрнутая формулировка: компилировать сырой исходный материал в профессиональные артефакты, которые удовлетворяют явным контрактам, опираются на свидетельства и остаются согласованными во всех выходах.

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

Эволюция продукта

1. Издатель docs-as-code. Портативный Markdown, diagrams-as-code, профессиональные темы и экспорт PDF, рендер локально в браузере.
2. SaaS-контур. Аутентификация, административная control plane, кредиты, биллинг и серверные AI-трансформации на AWS.
3. Стратегический разворот. Снизить приоритет проприетарного облачного workspace / хранения документов. Владеть трансформацией, а не документом.
4. Целевая платформа Compiler. Compiler - это контракт трансформации. Универсальный Harness исполняет этот контракт без жёстко прошитой оркестрации под каждый тип артефакта.

Реализовано и целевое

Реализовано

Рабочая система включает локально-ориентированный рендерер Markdown с Mermaid, иконками архитектуры, темами, изображениями, печатной вёрсткой и экспортом PDF; SPA и serverless-бэкенд, развёрнутые в AWS; идентичность через Cognito и административную control plane; runtime / версионированные промпты; тарифицируемые кредитами AI-трансформации; коммерческий контур вокруг Paddle.

Рабочие AI-трансформации сейчас есть как минимум для ADR, требований (FR/NFR, бизнес-правила, ограничения) и Resume / CV. Точный список Compiler, жизненный цикл публикации и режим биллинга (Live vs sandbox) следует подтверждать по продуктовому репозиторию.

Целевое / запланировано

Следующая архитектура - универсальный Transformation Harness, управляемый Artifact Contract, свидетельствами / каноническими фактами, настраиваемыми шаблонами выхода, Situations (пакеты из нескольких артефактов) и позднее Patch Compile. Здесь это не подаётся как уже развёрнутое поведение.

Концептуальный поток

flowchart TB
    src["Сырой исходник"]
    compiler["Compiler"]
    engine["Движок трансформации"]
    validate["Валидация / ремонт"]
    artifact["Профессиональный артефакт"]
    sinks["Markdown / YAML / Mermaid / PDF / Git"]

    src --> compiler
    compiler --> engine
    engine --> validate
    validate --> artifact
    artifact --> sinks

Валидация, ремонт, Git-native sinks и компиляция по контракту - целевой путь Harness. Реализованный путь сегодня - локальный рендеринг плюс AI-задачи на каждую трансформацию.

Основные акторы

Актор	Роль
Автор / профессиональный пользователь	Пишет или вставляет Markdown локально; экспортирует PDF; опционально запрашивает AI-компиляцию
Admin / Super Admin	Runtime-конфигурация, версии промптов, наблюдаемость трансформаций, публикация Compiler
Compiler	Контракт трансформации для одного класса профессионального артефакта
Harness	Целевая универсальная оркестрация, исполняющая контракт Compiler
LLM-провайдер	Сменяемая реализация модели, а не продуктовый ров

Основные возможности

Возможность	Статус
Рендеринг GFM / Markdown	Реализовано
Mermaid и иконки архитектуры	Реализовано
Профессиональные темы, печатная вёрстка, PDF	Реализовано
Локально-ориентированный рендеринг; содержимое по умолчанию остаётся в браузере	Реализовано
Аутентификация Cognito и RBAC	Реализовано
Runtime / версионированные промпты	Реализовано
Тарифицируемые кредитами AI-трансформации	Реализовано
Биллинговый контур Paddle	Реализовано; Live vs sandbox предстоит подтвердить
История трансформаций / административная наблюдаемость	Реализовано; глубину предстоит подтвердить
Универсальный Harness / Artifact Contract	Целевое
Evidence / Canonical Fact Model	Целевое
Situations и Patch Compile	Целевое

Технологический стек

Слой	Выбор	Роль
UI	Клиентский SPA	Локальный рендеринг, редактор, экспорт
Доставка	CloudFront + private S3 origin / OAC	Статический frontend
API	API Gateway + Lambda	Аутентифицированные серверные операции
Состояние	DynamoDB	Задачи, кредиты, runtime-конфиг, промпты
Идентичность	Amazon Cognito	Регистрация, аутентификация, роли
Инфра	Terraform	Воспроизводимое окружение AWS
CI/CD	GitHub Actions + OIDC	Деплой без долгоживущих облачных credentials
Интеллект	Внешний LLM API	Сменяемый компонент генерации
Биллинг	Paddle	Платежи как merchant of record

SQS, уведомления о результате по WebSocket, Step Functions и ECS Fargate фигурируют в архитектурном направлении; реализованными следует считать только фактически развёрнутые сервисы.

Роль и обязанности

Моя роль

Проект ведётся основателем end-to-end. Я владею продуктовой гипотезой, архитектурой и реализацией.

Работа включала:

• продуктовый discovery и позиционирование, включая разворот от идей издателя docs-as-code и workspace к платформе processing-layer / Compiler;
• определение требований и ограничений (local-first, кредиты, отсутствие проприетарного хранилища документов как ядра);
• архитектуру решения и системный анализ: доменная модель, жизненный цикл задачи, идентичность, биллинг и границы AI-трансформации;
• UX и проектирование продуктового workflow для локального рендеринга против явной серверной компиляции;
• архитектуру AWS: CloudFront / private S3, API Gateway, Lambda, DynamoDB, Cognito и связанные serverless-сервисы;
• инфраструктуру Terraform и CI/CD GitHub Actions с OIDC;
• проектирование аутентификации и авторизации (Cognito; USER / ADMIN / SUPER_ADMIN);
• архитектуру биллинга и кредитов (Paddle как merchant of record; кредиты как тарификация compute);
• архитектуру AI-трансформаций, проектирование промптов / контрактов и runtime-версионирование;
• стратегию наблюдаемости и качества (история трансформаций, административная control plane, целевой Compiler Health);
• компромиссы по приватности и стоимости;
• реализацию, отладку, dogfooding и приоритизацию дорожной карты.

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

Применение ИИ

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

Оставалось под ручным контролем:

• интерпретация требований и продуктовое позиционирование;
• доменное моделирование;
• архитектурные решения;
• границы приватности и стоимости;
• модель доступа;
• проектирование промптов / контрактов;
• код-ревью и отладка;
• решения по развёртыванию;
• техническая документация.

Архитектура и интеграции

Текущая архитектура

Реализованная система - клиентский SPA с serverless-бэкендом AWS для идентичности, биллинга, конфигурации и AI-задач.

Browser SPA
    -> CloudFront
    -> private S3 origin (OAC)

Аутентифицированные / серверные операции:
Browser
    -> API Gateway
    -> Lambda
    -> DynamoDB / SQS / внешние сервисы

Тела больших документов не являются payload бэкенда по умолчанию. Локальный рендеринг, Mermaid, темы, ассеты и операции с PDF выполняются в браузере. Содержимое отправляется на сервер, когда пользователь явно запускает AI-трансформацию.

AI-обработка использует асинхронную модель задач вокруг серверных workers и внешнего LLM-провайдера. Точное использование SQS, уведомлений по WebSocket и polling следует подтверждать по продуктовому репозиторию. Не читать Step Functions или ECS Fargate как уже развёрнутые, пока они не присутствуют в этом репозитории.

    C4Container
    title Диаграмма контейнеров DocCompile - реализовано

    Person(user, "Автор")
    Person(admin, "Администратор")

    System_Boundary(sys, "DocCompile") {
      Container(spa, "SPA", "Browser", "Локальный Markdown, Mermaid, PDF, UI компиляции")
      Container(cdn, "CloudFront", "CDN", "TLS, кэш, OAC к private origin")
      Container(static, "Frontend origin", "S3", "Статические ассеты SPA")
      Container(api, "API", "API Gateway + Lambda", "Задачи, кредиты, admin, billing hooks")
      ContainerDb(db, "Состояние", "DynamoDB", "Задачи, кредиты, конфиг, промпты")
    }

    Boundary(ext, "Внешние", "") {
      Container_Ext(cognito, "Cognito", "Идентичность")
      Container_Ext(llm, "LLM-провайдер", "API генерации")
      Container_Ext(paddle, "Paddle", "Платежи")
    }

    Rel(user, spa, "Использует локально")
    Rel(admin, spa, "Административная control plane")
    Rel(spa, cdn, "Загружает UI", "HTTPS")
    Rel(cdn, static, "Origin", "OAC")
    Rel(spa, cognito, "Вход")
    Rel(spa, api, "Аутентифицированные вызовы", "HTTPS JWT")
    Rel(api, db, "Читает/пишет")
    Rel(api, llm, "Задачи трансформации")
    Rel(api, paddle, "Webhooks / checkout")

architecture-beta
    service front(aws:cloudfront)[CloudFront]
    service static(aws:simple-storage-service)[Private S3 origin]
    service api(aws:api-gateway)[API Gateway]
    service lambda(aws:lambda)[Lambda]
    service dynamo(aws:dynamodb)[DynamoDB]
    service cognito(aws:cognito)[Cognito]
    service browser(logos:chrome)[Browser]
    service llm(logos:openai)[LLM provider]
    service paddle(logos:webhooks)[Paddle]

    browser:T --> B:front
    front:T --> B:static
    browser:R --> L:cognito
    browser:B --> T:api
    api:R --> L:lambda
    lambda:R --> L:dynamo
    lambda:B --> T:llm
    lambda:T --> B:paddle

Инфраструктура управляется Terraform. Деплои идут через GitHub Actions с OIDC, а не через долгоживущие облачные credentials.

Потоки интеграции

Локальная публикация. Браузер загружает SPA с CloudFront, рендерит Markdown / Mermaid локально и экспортирует PDF локально. Загрузки документа нет.

Аутентифицированная компиляция. Пользователь входит через Cognito, отправляет задачу трансформации через API Gateway, тратит кредиты и получает результат, когда worker завершается. LLM-провайдер - деталь реализации за этой задачей.

Биллинг. Checkout и покупка подписки / кредитов идут через Paddle. Бэкенд доверяет проверенным webhooks, а не браузеру, для платных entitlements.

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

Целевая / планируемая архитектура

Центральный будущий дифференциатор - универсальный Transformation Harness. В нём не должно быть жёстко прошитых ветвей вида if Resume / if ADR / if Requirements. Он исполняет контракт, который поставляет Compiler.

Source
  ↓
Suitability
  ↓
Fact / Evidence Extraction
  ↓
Generation
  ↓
Deterministic Validation
  ↓
Semantic Checking
  ↓
Repair
  ↓
Final Validation
  ↓
Artifact

Направление оркестрации:

API
  ↓
Step Functions
  ↓
generic stages / workers
  ↓
external LLM provider

flowchart TB
    api[API]
    sfn[Step Functions]
    suit[Suitability]
    gen[Generate]
    val[Deterministic validate]
    sem[Semantic check]
    repair[Bounded repair]
    fin[Finalize]
    llm[LLM provider]
    art[Artifact]

    api --> sfn
    sfn --> suit
    suit --> gen
    gen --> val
    val --> sem
    sem --> repair
    repair --> fin
    gen --> llm
    sem --> llm
    repair --> llm
    fin --> art

Возможности Harness (целевые): исполнение стадий, вызов модели, детерминированные валидаторы, семантические валидаторы, структурированные отчёты о нарушениях, ограниченные циклы ремонта, политики retry, provenance, учёт токенов / стоимости, трассировка исполнения, безопасные границы отмены.

Инвариант: добавление нового Compiler не должно требовать изменения ядра оркестрации Harness.

Будущее разделение compute

Compute	Когда
Lambda	Лёгкие / serverless-стадии
ECS Fargate	Тяжёлые ограниченные workers (например Chromium / детерминированная публикация), когда лимитов Lambda недостаточно
EC2 / GPU	Только если self-hosted inference или устойчивая нагрузка позднее это оправдают

Принцип: сначала serverless-оркестрация; специализированный compute только когда нагрузка его оправдывает. EC2 и контейнеры не входят в документированную текущую архитектуру.

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

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

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, явные демо-артефакты

Дорожная карта и демонстрация

Реализовано

Рабочий фундамент, как описано в продуктовых материалах (подтверждать по продуктовому репозиторию, прежде чем считать любую строку жёстким инвентарём):

• рендерер Markdown / GFM;
• Mermaid и иконки архитектуры;
• профессиональные темы, изображения/ассеты, печатная вёрстка, PDF, укрепление пагинации;
• local-first рендеринг в клиентском SPA;
• доставка AWS (CloudFront, private S3 / OAC);
• Terraform и GitHub Actions с OIDC;
• аутентификация Cognito и административная control plane с USER / ADMIN / SUPER_ADMIN;
• runtime-конфигурация и версионированные промпты с публикацией / откатом;
• AI-трансформации как минимум для ADR, требований (FR/NFR, бизнес-правила / ограничения) и Resume / CV;
• кредиты / контроль стоимости и биллинговый контур Paddle;
• история трансформаций и административная наблюдаемость.

Не заявлено как реализованное: Harness на Step Functions, workers на ECS Fargate, Evidence / Canonical Fact Model, Situations, Patch Compile, GitHub App / CLI как поставленный workflow.

Текущий / следующий фокус

Номера эпох предварительные. Предпочитать продуктовый репозиторий, если в нём более новая дорожная карта.

Эпоха	Фокус	Статус
-	Рендерер, SaaS-контур, первые AI-трансформации, кредиты / Paddle	Реализовано
E22	Телеметрия качества продукта и Compiler; жизненный цикл публикации Compiler (PUBLIC / INTERNAL / DISABLED)	Следующее
E23	Универсальный Transformation Harness; Artifact Contract	Запланировано
E24	Evidence / Canonical Fact Model	Запланировано
E25	Спецификация Compiler; пользовательские шаблоны выхода	Запланировано
E26	Эталонный Requirements Compiler	Запланировано
E27	API Contract Compiler; движок качества Mermaid	Запланировано
E28	Постранично точная публикация; укрепление Resume Compiler	Запланировано
E29	CLI / Git-native workflow	Запланировано
E30	Движок Situation	Запланировано
E31	Первые пакеты Situation	Запланировано
E32	Patch Compile	Запланировано
E33	Правила организации / пользовательские валидаторы	Запланировано
E34	Интеграция GitHub App / CI	Запланировано

Скриншоты и демо

Скриншоты в этом пакете не вымышляются. Добавлять проверенные ассеты в docs/assets/doccompile/, когда они есть в продуктовом репозитории. Рекомендуемый набор:

• editor_main.png - основной интерфейс редактора / compiler;
• mermaid_document.png - документ с Mermaid и иконками архитектуры;
• transformation_before_after.png - вход vs выход AI-трансформации;
• admin_history.png - история трансформаций / наблюдаемость для администратора.

Архитектура документирована диаграммами в Архитектура и интеграции, а не статическим PNG.

Live URL, примеры запросов и GIF следует линковать здесь только после подтверждения.

Что демонстрирует этот проект

Этот проект демонстрирует способность:

• поставить local-first движок публикации и serverless AWS SaaS-контур как один продукт;
• тарифицировать ИИ как ограниченную систему (задачи, кредиты, версионированные промпты), а не безграничный чат;
• развернуть гипотезу workspace, когда она конкурирует с существующим домом документов пользователя;
• спроектировать следующую архитектуру (Compiler, Harness, Artifact Contract), не выдавая её за уже развёрнутую.