clientsflow/docs/adr/0002-pocketbase-gvisor-microapps.md

ADR-0002: PocketBase + gVisor Platform For Agent-Built Microapps

Дата: 2026-03-23
Статус: accepted

Контекст

Нужен минимальный платформенный слой, в котором агент может собирать микро-приложения для клиентов по жёсткому шаблону:

• данные и auth живут в PocketBase;
• код приложения исполняется изолированно в Deno runtime;
• delivery идёт только из шаблонного репозитория и после валидации;
• control-plane хранится в основной Prisma-базе проекта.

Ключевые ограничения:

• агент не должен деплоить произвольный код вне шаблона;
• приложения разных клиентов должны быть логически и операционно изолированы;
• база данных и execution host разводятся в разные контуры;
• rollout и rollback должны опираться на versioned deploy records.

Решение

Принимаем MVP-схему из двух data-plane компонентов и одного control-plane:

1. PocketBase

• отдельный сервис данных для микро-приложений;
• каждое приложение получает собственный pocketbaseInstanceId и URL;
• доступ из микро-приложения идёт только через разрешённый service account.

2. Deno runner в gVisor

• каждое приложение исполняется как контейнер с runsc;
• runtime получает лимиты по CPU/RAM/PIDs и whitelist по env/network;
• runner запускает только Deno entrypoint из шаблона микро-приложения.

3. backend как control-plane

• хранит MicroAppProject, MicroAppRuntimeConfig, MicroAppDeployment;
• выдаёт конфиг для provisioning и delivery;
• знает путь репозитория, ветку, template checksum, preview/prod URL.

Поток

1. Агент создаёт проект только из microapps/templates/pocketbase-deno-dashboard.
2. Валидатор проверяет структуру репозитория и app.config.ts.
3. Control-plane создаёт или обновляет запись MicroAppProject.
4. Delivery pipeline фиксирует новую версию в MicroAppDeployment.
5. Runner поднимает Deno-контейнер через gVisor.
6. Публикация идёт через preview domain, а promotion в основной домен выполняется отдельно.

Delivery

• source of truth: git-репозиторий приложения;
• deploy unit: versioned template-compliant app directory;
• preview создаётся автоматически после успешной валидации;
• production переключается через отдельный promote шаг;
• rollback выполняется redeploy предыдущей записи MicroAppDeployment.

Домены

На первом этапе платформа хранит:

• primaryDomain
• previewDomain

Привязка доменов и DNS-автоматизация выносятся в отдельный шаг интеграции с Cloudflare и не блокируют запуск control-plane MVP.

Последствия

Плюсы:

• появляется единый control-plane для клиентских микро-приложений;
• есть жёсткий шаблон и проверяемый runtime policy;
• база данных и execution host разделены;
• есть основа для preview/prod flow и rollback.

Минусы:

• runtime по-прежнему требует отдельного delivery automation поверх git;
• provisioning PocketBase instance пока остаётся внешней операцией;
• домены и TLS-автоматизация ещё не включены в MVP-каркас.