DocCompile - всё вместе

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

Содержание

• Краткое описание
• Обзор
• Контекст и проблема
• Цели, требования и ограничения
• Роль и обязанности
• Модель системы
• Архитектура и интеграции
• Безопасность, качество и эксплуатация
• Решения, компромиссы и риски
• Дорожная карта и демонстрация
• Architecture Decision Records

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

Статус

Рабочий 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 фигурируют в архитектурном направлении; реализованными следует считать только фактически развёрнутые сервисы.

Контекст и проблема

Контекст

LLM и технические специалисты хорошо производят структурированный текст, Markdown, код, требования, диаграммы и архитектурные обсуждения. Превращение этого материала в профессиональный deliverable по-прежнему часто требует ручного копирования в Word, Google Docs или другой редактор документов.

Диаграммы - типичная точка разрыва. Mermaid sequence или C4-набросок живёт рядом с исходником в Git, затем его приходится перерисовывать или экспортировать в слайд или Word. Опубликованный PDF расходится с исходником. Docs-as-code workflow ломается на последней миле.

Поэтому исходный продукт сосредоточился на портативном пути:

портативный Markdown
-> diagrams-as-code
-> профессиональный рендеринг
-> PDF

Markdown остаётся источником истины. Продукт опирается на портативные стандарты: GFM / Markdown, Mermaid, иконки архитектуры, совместимые с Iconify, YAML front matter, обычные ссылки на изображения/ассеты и позднее потенциально LaTeX. Содержимое должно оставаться совместимым с Git / GitHub, VS Code / Cursor, MkDocs, инструментами Mermaid и обычным Markdown-тулингом.

Проблема

Две проблемы наложились друг на друга.

1. Последняя миля публикации

У профессионалов уже есть исходный материал. Им не нужно ещё одно место, где печатать. Им нужен надёжный способ:

• сохранить Markdown как рабочий формат;
• рендерить диаграммы без проприетарного холста;
• получить профессиональный PDF, совпадающий с исходником;
• не дать одной сломанной диаграмме обрушить весь документ;
• делать это без загрузки конфиденциальных черновиков в workspace, которым они не управляют.

Сырые заметки со встреч и транскрипты делают последнюю милю дороже. Эксперту всё равно приходится превращать сырой исходник в ADR, пакет требований, резюме или предложение. Эта работа повторяющаяся, её легко сделать чуть неправильно и трудно проверить.

2. Гравитация workspace

В ходе разработки продукта естественным расширением SaaS казалось проприетарное облачное хранилище документов: workspace, document management, более широкий редактор. Этот путь поставил бы DocCompile в конкуренцию за то, где живут документы - против Notion, Confluence, GitBook, Google Docs и собственного Git-репозитория пользователя.

Это неверная борьба для этого продукта. У технических пользователей уже есть дом для документов. Стоимость переключения высока. Workspace также тянет архитектуру к постоянному хранению документов, что конфликтует с позицией local-first по приватности.

Стратегический разворот

Решение:

Не владеть документом. Владеть трансформацией.

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

Возможные persistence и выходные sinks остаются там, где пользователь уже работает: локальные файлы, портативные пакеты, Git-репозитории, CLI, загрузки и позднее API / интеграции.

Интересная инженерная задача - не вызов LLM. Это построение контролируемой системы компиляции вокруг него: контракты, свидетельства, валидация, ремонт, границы стоимости и измеримое качество.

Цели, требования и ограничения

Цели и нецели

Основные цели проекта

• Сохранить портативные исходные форматы (Markdown / GFM, Mermaid, обычные ассеты) как рабочее представление.
• Получать профессиональные deliverable (печатная вёрстка и PDF) из этого исходника без проприетарного формата редактора.
• Поддержать diagrams-as-code, чтобы архитектурные и sequence-диаграммы оставались в том же файле, что и текст.
• Изолировать сбои рендеринга, чтобы одна сломанная диаграмма не ломала весь документ.
• Сохранить client-side-first / локальное поведение для рендеринга, стилей, локальных ассетов и операций с PDF.
• Сделать использование ИИ финансово ограниченным через кредиты и контроль стоимости.
• Сделать поведение ИИ конфигурируемым и версионируемым независимо от деплоев приложения.
• Обеспечить историю трансформаций и административную наблюдаемость серверных AI-задач.
• Двигаться к явным Artifact Contract: компиляция успешна, выдала предупреждения или завершилась ошибкой.
• Поддержать Git-native выходы, чтобы артефакт мог вернуться в существующий workflow пользователя.

Что не входит в проект

• Не является универсальным облачным workspace для документов или заменой Notion/Confluence.
• Не является WYSIWYG-клоном Word и не делает проприетарный блочный редактор источником истины.
• Не является гарантией отсутствия галлюцинаций в AI-выходе. Целевые проверки - детерминированная валидация, привязка к исходнику и ограниченный ремонт - а не недоказуемое утверждение «полностью верифицированный ИИ».
• Не привязан навсегда к одному вендору LLM.
• Не выдумывает отсутствующие профессиональные факты, если в исходнике нет свидетельств; неразрешённые пункты должны оставаться неразрешёнными.
• Не включает формальные значения SLA / RTO / RPO в этом портфолио-пакете. Эти значения - Unknown / TBD, пока они не определены в эксплуатационных артефактах проекта.
• Текущая архитектура не предполагает EC2 или постоянно работающие контейнеры, если их нет в продуктовом репозитории.

Требования

Бизнес-требования

• BR-001. Портативный источник истины.
  Пользователь должен иметь возможность работать в Markdown (GFM), с Mermaid, иконками архитектуры, YAML front matter и обычными ссылками на изображения, без конвертации в проприетарный формат хранения.

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

• BR-003. Local-first по умолчанию.
  Рендеринг, стили, локальные ассеты, Mermaid и локальные операции с PDF должны работать в браузере. Содержимое документа не должно покидать браузер, пока пользователь явно не запросит серверную операцию.

• BR-004. Ограниченная AI-компиляция.
  Серверные AI-трансформации должны тарифицироваться (кредиты), контролироваться по стоимости и быть атрибутируемыми к пользователю и типу трансформации.

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

• BR-006. Идентичность и администрирование.
  Аутентифицированные SaaS-операции должны использовать управляемую идентичность. Должна существовать административная control plane для конфигурации, наблюдаемости и повышенных ролей.

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

• BR-008. Направление Artifact Contract.
  Продукт должен эволюционировать от «модель что-то сгенерировала» к явному результату компиляции: успех, предупреждения или ошибка относительно контракта Compiler.

• BR-009. Направление привязки к свидетельствам.
  Важные утверждения в выходе должны становиться трассируемыми к исходным свидетельствам. Отсутствующие свидетельства нельзя молча заполнять.

• BR-010. Git-native выходы.
  Скомпилированные артефакты должны иметь возможность вернуться в локальные файлы, загрузки и позднее Git / CLI workflow, а не оставаться запертыми в проприетарном хранилище.

В публичной версии приведён сокращённый фрагмент требований. Внутренние суммы биллинга, тексты промптов и неопубликованные контракты Compiler не раскрываются.

Правила и ограничения

Business Rules

• RULE-001. Локальная работа не требует загрузки.
  Открытие, редактирование, рендеринг и экспорт документа локально не должны требовать отправки тела документа на бэкенд.

• RULE-002. Серверная обработка явна.
  Содержимое отправляется на бэкенд только когда пользователь вызывает серверную возможность, например AI-компиляцию.

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

• RULE-004. Не выдумывать отсутствующие факты.
  Компиляция не должна представлять неподтверждённые профессиональные факты так, будто они были в исходнике. Неразрешённые решения остаются неразрешёнными.

• RULE-005. Инварианты Compiler выше шаблонов.
  Пользовательский шаблон выхода может менять структуру артефакта. Он не должен ослаблять гарантии Compiler (привязка к свидетельствам, валидаторы, границы ремонта).

• RULE-006. LLM-провайдер сменяем.
  Ценность продукта лежит в спецификациях Compiler, контрактах, моделях свидетельств, валидаторах, ремонте и оценке качества - а не в одном промпте или одном вендоре.

Ограничения

• CON-001. Serverless-архитектура под руководством основателя, чувствительная к стоимости.
  Стоимость простоя должна оставаться низкой. Постоянно работающие бэкенды избегаются, пока нагрузка их не оправдывает.

• CON-002. Без ненужного постоянного бэкенда документов.
  Система не должна требовать проприетарного облачного хранения документов для основного пути публикации.

• CON-003. Без обязательной аутентификации для чисто локальных / бесплатных функций.
  Идентичность нужна для SaaS / AI / биллинговых операций, а не для локального рендеринга.

• CON-004. Приватно-чувствительное профессиональное содержимое.
  Черновики могут включать неопубликованную архитектуру, требования и персональные карьерные данные. Обработка по умолчанию остаётся в браузере.

• CON-005. Инфраструктура AWS должна воспроизводиться через Terraform.
  Продакшен-окружение - не click-ops в консоли.

• CON-006. Сначала serverless-оркестрация.
  Специализированный compute (например ECS Fargate) вводится только когда границ Lambda недостаточно. EC2 / GPU - только если будущий self-hosted inference или устойчивая нагрузка это оправдают.

• CON-007. Формальные операционные SLA - TBD.
  Этот портфолио-пакет не выдумывает цели RTO / RPO / доступности.

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

Моя роль

Проект ведётся основателем 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 применялись для ускорения рутинной реализации, генерации шаблонного кода и быстрых итераций. Они не рассматривались как авторы или владельцы системы.

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

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

Модель системы

Доменная модель

Реализованный домен - локально-ориентированный издатель плюс serverless-контур AI-трансформаций. Будущие концепции Compiler / Harness перечислены отдельно и не входят в текущую модель данных.

Реализованные концепции

Концепция	Смысл
User	Аутентифицированная идентичность из Cognito
Role	USER, ADMIN, SUPER_ADMIN
Compiler	Именованный тип трансформации (исторически «Template») для класса артефакта
Compiler version	Исполняемая ревизия конфигурации Compiler / промпта
Output template	Презентационная структура артефакта; сейчас слабее отделена от логики Compiler, чем в целевой модели
Compile run / transformation job	Асинхронная серверная AI-задача со статусом, стоимостью и обработкой результата
Artifact	Сгенерированный Markdown / документный выход запуска
Credit account	Баланс пользователя для compute-тяжёлых операций
Credit ledger entry	Атрибутируемое списание / начисление использования
Runtime configuration	Серверные настройки, которые можно менять без деплоя
Prompt definition / prompt version	Версионированное поведение ИИ с публикацией / откатом
Audit event	След чувствительных административных действий и трансформаций

Точные имена таблиц и атрибуты в публичном пакете опущены.

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

Их нельзя читать как реализованные сущности:

Концепция	Смысл
Artifact Contract	Объективное определение успеха для Compiler: разбор, схема, свидетельства, ограничения вёрстки
Fact	Каноническое извлечённое утверждение со статусом (asserted / uncertain / conflicting / unknown)
Evidence	Указатель происхождения от Fact обратно к исходному материалу
Situation	Оркестрация нескольких Compiler вокруг одной цели пользователя
Artifact pack	Набор связанных артефактов, которые должны оставаться согласованными
Patch Compile	Brownfield-обновление существующего артефакта вместо полной регенерации

Контекстная диаграмма

    C4Context
    title Системный контекст DocCompile

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

    System(dc, "DocCompile", "Локально-ориентированный издатель и сервис AI-компиляции")

    System_Ext(llm, "LLM-провайдер", "Сменяемый API генерации")
    System_Ext(paddle, "Paddle", "Биллинг merchant of record")
    System_Ext(idp, "Amazon Cognito", "Идентичность")

    Rel(author, dc, "Рендерит локально; запрашивает компиляцию")
    Rel(admin, dc, "Конфиг, промпты, наблюдаемость")
    Rel(dc, idp, "Аутентифицирует")
    Rel(dc, llm, "Задачи трансформации")
    Rel(dc, paddle, "Checkout и webhooks")

Модель данных

Высокоуровневая реализованная модель

erDiagram
    USER ||--o{ CREDIT_ACCOUNT : holds
    USER ||--o{ TRANSFORMATION_JOB : requests
    USER ||--o{ AUDIT_EVENT : generates

    CREDIT_ACCOUNT ||--o{ CREDIT_LEDGER_ENTRY : records

    COMPILER ||--o{ COMPILER_VERSION : versions
    COMPILER_VERSION ||--o{ PROMPT_VERSION : uses
    COMPILER_VERSION ||--o{ TRANSFORMATION_JOB : executes

    RUNTIME_CONFIG ||--o{ PROMPT_VERSION : publishes

    TRANSFORMATION_JOB ||--o| ARTIFACT : produces
    TRANSFORMATION_JOB }o--|| CREDIT_LEDGER_ENTRY : meters

    USER {
        string id PK
        string role
    }

    COMPILER {
        string id PK
        string name
        string publication_state
    }

    COMPILER_VERSION {
        string id PK
        string compiler_id FK
        string status
    }

    PROMPT_VERSION {
        string id PK
        string body
        string published
    }

    TRANSFORMATION_JOB {
        string id PK
        string user_id FK
        string compiler_version_id FK
        string status
        string cost_units
    }

    ARTIFACT {
        string id PK
        string job_id FK
        string format
    }

    CREDIT_ACCOUNT {
        string id PK
        string user_id FK
        int balance
    }

    CREDIT_LEDGER_ENTRY {
        string id PK
        string account_id FK
        int delta
        string reason
    }

    RUNTIME_CONFIG {
        string id PK
        string key
        string value
    }

    AUDIT_EVENT {
        string id PK
        string actor_id FK
        string action
    }

publication_state (PUBLIC / INTERNAL / DISABLED) - целевой жизненный цикл Compiler. Если продуктовый репозиторий ещё не сохраняет его, считать запланированным.

Целевая модель фактов (не реализована)

Fact
├── id
├── concept
├── value
├── status: asserted | uncertain | conflicting | unknown
├── evidence[]
├── source
└── provenance

Примеры доменных фактов (планируются): RequirementFact, BusinessRuleFact, ConstraintFact, NfrFact, EndpointFact, EmploymentFact, SkillFact.

Ключевая идея модели

Центр тяжести реализации - transformation job: явный, тарифицируемый, асинхронный запрос компиляции. Локальные документы не являются источником истины системы в облаке; они остаются у пользователя, пока не запрошена задача.

Целевой центр тяжести - контракт Compiler: входной контракт, схема фактов, контракт артефакта, валидаторы, стратегии ремонта и метрики качества. Добавление Compiler не должно требовать изменения оркестрации Harness.

Концепция Compiler

Compiler - это не просто каркас Markdown. Это контракт трансформации для конкретного класса профессионального артефакта:

Compiler
├── Input Contract
├── Fact Schema
├── Artifact Contract
├── Evidence / Grounding Rules
├── Output Template
├── Validators
├── Repair Strategies
├── Presentation Constraints
└── Quality Metrics

Архитектурный принцип (целевой):

Artifact Contract
=
Compiler Invariants
+ Output Template
+ User Options
+ Organization Rules

Пользовательский шаблон может менять структуру артефакта, но не должен ослаблять гарантии Compiler.

Примеры текущих / планируемых Compiler: ADR; Requirements Specification; Resume / CV; API Contract; System Design; Meeting Summary; Proposal; Executive Summary. Как рабочие трансформации сегодня заявлены только первые из списка.

API-контракты

Имена эндпоинтов в публичном пакете иллюстративны. Бэкенд предоставляет REST/JSON API для SaaS-операций, закрытых идентичностью. Локальный рендеринг через этот API не идёт.

Группы возможностей:

• аутентификация через Cognito;
• submit / status / result задачи трансформации;
• баланс кредитов и ledger;
• административная runtime-конфигурация и версии промптов;
• биллинговые webhooks от Paddle.

Слои безопасности:

• JWT от Cognito на аутентифицированных маршрутах;
• проверки ролей для операций ADMIN / SUPER_ADMIN;
• секреты и ключи провайдера остаются на сервере;
• маршруты webhook проверяют подписи Paddle;
• результаты задач доступны владельцу, кроме административной наблюдаемости.

Жизненный цикл задачи трансформации (реализованное направление)

submit
-> queued / running
-> succeeded | failed
-> result available to owner

Имена статусов в коде могут отличаться. Инвариант: задача атрибутируема, тарифицируема и инспектируема; это не свободная чат-сессия.

Паттерн обработки ошибок

Типичные статусы:

200 OK                  успешное чтение
202 Accepted            задача принята
400 Bad Request         некорректный ввод
401 Unauthorized        отсутствует или невалидна идентичность
403 Forbidden           аутентифицирован, но не разрешено
404 Not Found           ресурс отсутствует или невидим
409 Conflict            конфликт состояния
429 Too Many Requests   лимит частоты или кредитов

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

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

Реализованная система - клиентский 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 и контейнеры не входят в документированную текущую архитектуру.

Безопасность, качество и эксплуатация

Модель безопасности и доступа

Идентичность

Аутентифицированные SaaS-операции используют Amazon Cognito. Локальный рендеринг и экспорт PDF не требуют идентичности.

Заявленные RBAC-роли: USER, ADMIN, SUPER_ADMIN. Точную матрицу прав следует подтверждать по продуктовому репозиторию.

Авторизация на бэкенде

API Gateway и Lambda обеспечивают идентичность на серверных маршрутах. Административная runtime-конфигурация, публикация / откат промптов и наблюдаемость между пользователями ограничены повышенными ролями. Ключи API провайдера и секреты биллинга остаются на сервере.

Инфраструктура

• private S3 origin для SPA, доступ через CloudFront OAC, а не публичный website bucket;
• least-privilege IAM для ролей, управляемых Terraform;
• GitHub OIDC для деплоев (без долгоживущих access keys деплоя в CI);
• проверка подписи webhook Paddle до изменения кредитов или entitlements;
• контроль злоупотреблений и стоимости вокруг задач трансформации (кредиты, rate limits).

Приватность

Local-first рендерер: Markdown, Mermaid, стили, локальные ассеты и локальные операции с PDF выполняются в браузере. Обязательной загрузки для локальной работы с документом нет.

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

Телеметрия задумана как приватно-осознанные операционные данные, а не как ещё одно хранилище документов. Отредактированный текст документа не должен загружаться лишь для расчёта сигналов качества (например локальных корзин edit-distance). Не следует перечитывать это как сертифицированную программу приватности; юридические документы нужно проверять отдельно.

Качество

Текущее

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

Глубину истории, телеметрию качества и состояния публикации Compiler (PUBLIC / INTERNAL / DISABLED) следует подтверждать по продуктовому репозиторию.

Целевое

• Artifact Contract как определение успеха;
• детерминированные валидаторы (разбор, схема, обязательные разделы, отрисовываемые диаграммы);
• проверки семантической согласованности (вероятностные; не «AI verified»);
• привязка к свидетельствам;
• ограниченные циклы ремонта;
• метрики Compiler Health: доля успеха, доля принятия, принято без правок, доля ремонта, сбои валидации, стоимость, латентность.

Детерминированная валидация и вероятностная семантическая проверка - разные вещи. Второй проход LLM не считается доказательством.

Направление телеметрии качества

Сигнал	Смысл
Pipeline trace	Операционный путь отдельного Compile
Outcome signal	Accept / accept with edits / reject / regenerate / export / abandon
Aggregate Compiler Health	Метрики по Compiler / версии / шаблону

Долгосрочный ров зависит от измеримого улучшения качества, а не от накопления сырых логов.

Нефункциональные требования

Атрибут	Сценарий	Подход
Privacy	Черновик ADR не должен загружаться только чтобы предпросмотреть PDF	local-first рендерер
Security	USER не должен публиковать конфигурацию промптов	роли Cognito, серверная авторизация
Cost	Сорвавшаяся компиляция не должна безгранично биллить основателя	кредиты, лимиты задач, сменяемый провайдер
Operability	Окружение должно быть пересобираемым	Terraform, GitHub Actions OIDC
Change isolation	Поведение ИИ меняется без деплоя приложения	runtime / версионированные промпты
Integrity	Отсутствующие исходные факты не должны появляться как истина	целевое: fail или warn вместо выдумывания

Режимы отказа

Риск	Последствие	Митигирующая мера
Регрессия промпта или модели	Худшие артефакты в продакшене	версии промптов, откат, публикация INTERNAL
Безграничная стоимость LLM	Bill shock	кредиты, лимиты, таймауты задач
Подделка webhook	Фиктивные начисления кредитов	проверка подписи Paddle
Публичный S3 origin	Раскрытие ассетов или конфига	private origin + OAC
Долгоживущие ключи CI	Утечка credentials	GitHub OIDC
Театр семантических проверок	Ложная уверенность в выходе	различать детерминированные и вероятностные проверки
Путаница local/cloud	Пользователь думает, что содержимое осталось локальным после compile	явное действие компиляции

Оценка масштаба и стоимости

Основные драйверы нагрузки

• локальный рендеринг (CPU клиента; не тарифицируется как AWS compute);
• частота задач трансформации и объём токенов;
• запросы административной наблюдаемости;
• трафик CloudFront для SPA;
• чтения/записи DynamoDB для задач, кредитов и конфига.

Основные драйверы стоимости

• использование LLM-провайдера (доминирующая переменная стоимость);
• Lambda / API Gateway;
• DynamoDB;
• CloudFront и S3;
• Cognito MAU;
• комиссии Paddle;
• хранение наблюдаемости.

Уровни масштабирования

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

Эксплуатация

• Terraform для AWS;
• GitHub Actions для сборки и деплоя;
• логи / метрики в аккаунте AWS (точные бэкенды в этом пакете TBD);
• защита кредитов / стоимости на задачах;
• runtime-конфигурация и административная control plane;
• откат промптов без повторного деплоя приложения.

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

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

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), не выдавая её за уже развёрнутую.

Architecture Decision Records

См. Architecture Decision Records.