# 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-каркас.