DocCompile - SRS-сборка

Эта страница собирает разделы для спецификации требований к ПО: от контекста и проблемы до безопасности, качества и эксплуатации.

Содержание

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

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

Статус

Рабочий 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, которое проектируется следующим.

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

Контекст

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;
• откат промптов без повторного деплоя приложения.