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

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

Цели и нецели¶

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

Сохранить портативные исходные форматы (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 / доступности.

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

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

Реализованный домен - локально-ориентированный издатель плюс 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, явные демо-артефакты