Веб-адмінка — це вікно, а не друге джерело істини

Веб-панель адміністрування APX не є центром системи.

Дизайн суворий. Демон володіє станом. Веб-інтерфейс (UI) — це локальний клієнт. Ця відмінність має значення. Вона визначає, де зберігається істина і наскільки великим може бути розсинхрон даних.

APC забезпечує портативний шар контексту. APX забезпечує шар середовища виконання (runtime) та інструментарію. Веб-адмінка належить APX. Вона дозволяє переглядати runtime у браузері. Вона не зберігає власну копію «істини» проєкту.

Архітектура працює так:

  • Демон запускає локальний HTTP-сервер.
  • Кожен інтерфейс взаємодіє з демоном через HTTP.
  • Веб-адмінку обслуговує демон.
  • Браузер отримує токен від демона.

Браузер не є рівноправною базою даних. Це лише один із інтерфейсів. Коли веб-панель стає другим джерелом істини, вона стає непрацездатною.

Дві копії стану призводять до помилок:

  • CLI записує одне, тоді як UI показує інше.
  • Сесія в браузері редагує конфігурацію, але демон використовує застарілі дані.
  • Оновлення сторінки показує один проєкт, тоді як інша вкладка відображає застарілі дані.
  • Виправлення в UI ніколи не досягає реального runtime.

APX уникає цього, роблячи браузер «тонким». UI запитує демона. Демон запитує ядро (core). Ядро читає або записує дані в реальне сховище (backing store). Цей ланцюжок простий. Простота — це добре.

Хороша локальна панель робить три речі:

  • Показує поточний стан.
  • Надсилає невелику дію.
  • Перевіряє актуальність після дії.

Панель дозволяє переглядати проєкти, агентів, рутини, сесії, MCP та налаштування. Це лише представлення системи, а не її форк.

Деталі реалізації забезпечують локальність:

  • Режим розробки використовує Vite і проксіює запити до демона.
  • У продакшені демон обслуговує зібраний додаток.
  • Принцип одного походження (same origin) спрощує автентифікацію та маршрутизацію.
  • Браузеру ніколи не потрібен прямий доступ на запис до репозиторію.

Перевага не у візуальному досконалінні. Перевага в тому, що кожна дія проходить через один бекенд.

Якщо ви редагуєте налаштування в панелі, вона надсилає зміну демону. Демон оновлює сховище проєкту. Наступний рендеринг зчитує те саме джерело істини, що й CLI. Одна система — багато інтерфейсів.

UI може зникнути без шкоди для вашого проєкту. Ви можете закрити вкладку або змінити пристрій. Стан залишається в демоні та в папці .apc/.

Ментальна модель проста:

  • APC: чим є проєкт.
  • APX: як проєкт працює.
  • Веб-адмінка: одне вікно в цей runtime.

Дотримуйтесь чіткості цього кордону. Стек залишається замінним. Браузер залишається опціональним. Демон залишається головним. Проєкт залишається портативним.

Source: https://dev.to/agentprojectcontext/the-web-admin-is-a-window-not-a-second-source-of-truth-2aip

Optional learning community: https://t.me/GyaanSetuAi