Архітектура

Як це працює

Сторінка для нетехнічного читача — директор, Вова, тех-писці. Пояснює, де живуть дані, хто чим користується, і як саме система генерує звітний документ за пів-хвилини замість двох днів.

На що відповідає система

Три питання, які зараз вирішуються руками. Кожне — окрема секція матриці й окремий запит у Claude Desktop.

Чи всі вимоги ТВ покриті в ТЗ?

Coverage gap detection: матриця має по рядку на кожну вимогу ТВ. Якщо колонка «ТЗ §» порожня — це gap, який підсвітиться червоним і ляже у звіт перевірки покриття.

→ автоматичний gap-report

Чи всі вимоги ТЗ відображені в інструкціях і методиках?

Поля matrix.docs[] і matrix.tests[] зв'язують вимогу з §-розділами інструкцій, програм випробувань, методик і протоколів. Колонка «Покриття» показує, де саме вимогу описано.

→ traceability на 100% документів

Чи готові всі звітні документи постанови №205?

Document tracker (Confluence) → 14-17 документів на проєкт зі статусами, версіями, авторами, дедлайнами. Видно, які з них згенеровані, які — у Drive вручну, які — ще не починали.

→ checklist для здачі етапу

Де живуть дані

Чотири джерела, одна система.

Жодних копій, жодного нового сховища документів. Confluence залишається трекером, Drive — джерелом документів, Postgres тримає лише матрицю й аудит, а KB-репозиторій з ДСТУ і постановами захований під капотом.

Confluence

Index / Tracker

Трекери 15+ проєктів
Чек-лісти SOD-полісі
Метадані документів
Посилання на .gdoc у Drive

read-only adapter

Google Drive

Source of truth · документи

Самі .gdoc у папках проєктів
Skeleton-шаблони
Find-and-replace in place
Без копій (SOD-полісі)

Google Docs API · batchUpdate

Postgres

Internal · з Phase 1

Requirements Matrix
History / changelog
Version locks
Audit trail генерацій

лише ми, користувач не бачить

KB git-репо

Knowledge Base

Постанови, ДСТУ
Шаблонні фрагменти
Промпти, конфіги
Версіонується git tag

internal · через KB-editor у вебі

zvitnist backend

Python · FastAPI · FastMCP

orchestrationdoc-enginematrix CRUD

Читає

Confluence-трекери
Drive: skeleton + project folders
Postgres: matrix, history
KB git: постанови, ДСТУ

Пише

Drive: новий .gdoc у папку проєкту
Postgres: matrix rows, audit
Confluence: статуси (опціонально)
Footer-коменти з audit trail

Викликає

Google Docs API · batchUpdate
Anthropic API · LLM-секції
Confluence REST · метадані
FastMCP · tools для Claude Desktop

Claude Desktop

MCP клієнт · для Вови

Чат як у Slack
MCP-tools викликають бекенд
0 коду, 0 CLI

Web-адмінка

HTTP · для адмінів і Romina

CRUD матриці
KB-editor + template-config
Generation history

Хто яким інтерфейсом користується

Дві аудиторії — два інтерфейси. Один і той самий бекенд під капотом.

Для Вови — Claude Desktop

Щоденна робота, без коду, без терміналу

Tooling = MCP-сервер, хоститься Іваном. Вова просто відкриває Claude Desktop і пише природною мовою. Жодного git, IDE, YAML чи Python — те, що було перешкодою у власному скрипті Вови.

Засіди матрицю Vector з ТЗ

Готово. 47 рядків, 23 з них співпали з існуючими — позначив дублі. Approve у вебі: /projects/vector/matrix

Згенеруй методику для Vector етап 1

Створив попередній_методика-випр_Vector_етап-1.gdoc у Drive · Vector / Документація. 17 з 17 рядків матриці підтягнуто.

Типові запити

>«Засіди матрицю Vector з ТЗ»
>«Згенеруй методику для Vector етап 1»
>«Які вимоги ще без покриття?»
>«Покажи статус документів Vector»

Подивитися сценарій

Для адмінів — web-UI

Romina, тех-ліди, admin — те, що не вліщується в чат

Адмінка — для дій, де потрібна таблиця, форма, історія. Не для повсякденного користування: щоденне — у Claude Desktop. Сюди заходять, щоб approve матрицю, налаштувати шаблон, підкрутити KB.

zvitnist · Vector · Matrix

VEC-3.2.1Вимога ТВ …

VEC-4.1.1Вимога ТВ …

VEC-4.2.1Вимога ТВ …

VEC-3.3.3Вимога ТВ …

Що тут роблять

CRUD Requirements Matrix
Template config — форма, не YAML
KB editor — візуальний, не markdown
Generation history + diff

Відкрити матрицю Vector

Конвеєр генерації

Як саме створюється звітний документ.

Шість кроків від запиту в Claude Desktop до готового .gdoc у папці проєкту. Без копій документів, із footer-коментом-аудитом на кожну згенеровану версію.

Запит у Claude Desktop

Користувач пише в чат. Claude підбирає відповідний MCP-tool, наприклад generate_test_program(project="vector", stage=1). MCP-tool — це звичайна HTTP-ручка нашого бекенду, обгорнута FastMCP.

Бекенд читає Requirements Matrix

Postgres-запит → беруться лише covered рядки потрібного етапу. Кожен рядок — джерело даних для рядка таблиці у документі (вимога, посилання на ТЗ, метод перевірки, очікуваний результат).

Drive API: files.copy → новий .gdoc

Skeleton-шаблон копіюється у канонічний шлях проєкту: Vector / Документація / попередній_методика-випр_Vector_етап-1.gdoc. Це новий згенерований документ за каноном шляху SOD-полісі, а не дубль існуючого.

Google Docs API: batchUpdate

Три типи операцій в одному запиті: replaceAllText для plain-плейсхолдерів ({{project_name}}), tableCell-операції для динамічних таблиць (рядок на кожен елемент матриці), insertText у named ranges для довгих секцій.

Anthropic API → LLM-секції (опціонально)

опціонально

Для секцій, які треба перефразувати під проєкт — вступ, висновки, обґрунтування методу. Результат вертається у бекенд, який знову викликає batchUpdate. LLM займає ~20-30% workflow, не більше.

Footer-коментар: audit trail

В кінці документа автоматично вставляється коментар: Згенеровано zvitnist v0.4 / template v2.1 / KB 2026-03-25 / matrix snapshot ABC123. Через місяць можна точно сказати, з яких даних зібраний файл.

Межі системи

Що ми НЕ робимо.

Кожна з цих меж — свідомий вибір. Або це вже добре працює в наявних інструментах (Google Docs, Confluence), або це порушує SOD-полісі, або це створює зайве lock-in. Менше — це одночасно і простіше, і дешевше підтримувати.

Не створюємо копії документів

SOD-полісі забороняє. Find-and-replace in place в одному файлі.

Не редагуємо готовий текст документа

Це робиться нативно в Google Docs — Вова там сидить щодня.

Не редагуємо skeleton-и через адмінку

Skeleton — це теж Google Docs. Адмінка лише прив'язує його до шаблону.

Не заміняємо Confluence для трекінгу

Трекери проєктів живуть у Confluence. Ми лише читаємо метадані.

Не вимагаємо git / IDE / terminal / YAML

Вова — не девелопер. Чат + веб-форми. Жоден код не торкається користувача.

Не lock-in на один LLM

Anthropic API сьогодні; pluggable adapter — можна замінити на іншого провайдера.

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

Чим це збирається. Стандартні зрозумілі компоненти, без екзотики.

Backend

Phase 0 → 1

Python + FastAPI
HTTP API, orchestration, бізнес-логіка
Google Docs API + Drive API
Основний doc-engine — batchUpdate, files.copy
python-docx
Fallback для не-Google тенантів (рідкісно)
FastMCP
Обгортка HTTP-ручок у MCP-tools для Claude Desktop
Anthropic SDK
LLM-операції — 20-30% workflow (LLM-секції, парсинг ТЗ)
Confluence REST API
Read-only adapter — метадані, трекери проєктів
PostgreSQL
Requirements Matrix, history, audit trail (Phase 1+)

Frontend / Data

UI + data layer

Next.js 14 (App Router, TS)
Веб-адмінка — CRUD матриці, template-config, KB-editor
Tailwind CSS
Linear/Notion-стиль, без UI-бібліотек
Claude Desktop
Інтерфейс №1 — для щоденної роботи Вови, Romina
Google Drive (org)
Документи .gdoc — джерело правди, без копій
Confluence (org)
Трекери проєктів, чек-лісти, метадані
Internal git репо · KB
Постанови, ДСТУ, шаблонні фрагменти — користувач не бачить
Pluggable storage adapters
SaaS-варіанти: Notion, SharePoint, локальний DOCX

Готові подивитися на UX в дії?

Сценарій у Claude Desktop або повна матриця проєкту Vector — у два кліки.

Сценарій у Claude Desktop Матриця Vector