beeui 0.13.0

Reusable UI framework for Bee products

BeeUI — reusable UI framework для Bee-продуктов

BeeUI — общий Python-based UI framework для Bee-продуктов: beecap, beeagent и будущих модулей Bee ecosystem.

Iteration 11

Текущий deliverable — Generic artifact browser v1: read-only просмотр артефактов через ProductUiAdapter.

Уже работает:

• всё из Iteration 10: create_beeui_app(...), mount_beeui(...), adapter injection, product metadata, mount path validation;
• uv sync --frozen --extra dev;
• uv run pytest -q;
• ./start.sh doctor;
• ./start.sh version;
• ./start.sh routes;
• ./start.sh web --host 127.0.0.1 --port 8780;
• import beeui_module;
• schema-driven theme/layout/navigation в config/schema.yml;
• schema-driven literal и resolver-backed blocks в config/schema.yml;
• read-only demo data source;
• read-only static YAML/JSON data source;
• stable resolver envelope для controlled block value resolution;
• dashboard blocks рендерятся из top-level blocks и pages[].blocks[];
• generic adapter contract package src/beeui_module/adapters/;
• stable adapter envelopes (ok|partial|error) and stable adapter errors;
• safe adapter ID helpers for product_id, run_id, artifact_id, action_id;
• BeeCap-compatible fixture adapter BeeCapFixtureAdapter;
• controlled BeeCap-like fixtures under tests/fixtures/beecap/;
• BeeCap adapter fixture tests in tests/test_beecap_adapter.py;
• integration boundary docs in docs/INTEGRATION.md;
• embedded BeeCap example in examples/beecap_embedded/beeui.yml;
• GET /runs/{run_id}/artifacts — HTML список артефактов;
• GET /runs/{run_id}/artifacts/{artifact_id} — HTML preview артефакта;
• GET /api/runs/{run_id}/artifacts — JSON API список артефактов;
• GET /api/runs/{run_id}/artifacts/{artifact_id} — JSON API preview артефакта;
• JSON preview с redaction;
• JSONL preview до 500 строк с row-level warnings;
• text preview до 100 000 символов;
• unsupported/binary artifacts отображаются как metadata-only;
• malformed JSON/JSONL не ломают страницу/API;
• large JSON/JSONL preview ограничен 512 KB;
• safe run_id / artifact_id validation;
• redaction placeholder для secret, token, password, api_key, api_secret;
• доступ к артефактам идёт только через ProductUiAdapter.list_artifacts() и ProductUiAdapter.read_artifact();
• при отсутствии adapter возвращается explicit 503 unavailable state;
• features.browser_artifact включает/отключает HTML/API artifact routes;
• features.api остаётся зарезервированным для будущего stable BeeUI API и не отключает artifact browser API routes;
• create_beeui_app(settings, ui_config, *, config_path, product_id, product_title, adapter);
• mount_beeui(parent_app, *, path, ...) для встраивания BeeUI в родительское FastAPI приложение;
• app.state.beeui_adapter — сохранение adapter instance;
• app.state.beeui_product — сохранение product metadata;
• runtime-валидация adapter на соответствие минимальному протоколу ProductUiAdapter;
• валидация mount path (безопасный путь, без path traversal);
• проверка коллизии маршрутов при mount;
• embedded API тесты в tests/test_embedded.py.

Поддерживаемые типы блоков:

• metric_card;
• kpi_grid;
• status_card;
• table_card;
• links_card;
• alert_card;
• text_card;
• progress_card.

Минимальная web surface после Iteration 11:

• GET /
• GET /runs
• GET /components
• GET /components/interface
• GET /components/forms
• GET /components/layout
• GET /components/extra
• GET /components/plugins
• GET /health
• GET /static/...
• GET /static/vendor/tabler/css/tabler-compatible.min.css
• GET /static/vendor/tabler/js/tabler-compatible.min.js
• GET /runs/{run_id}/artifacts
• GET /runs/{run_id}/artifacts/{artifact_id}
• GET /api/runs/{run_id}/artifacts
• GET /api/runs/{run_id}/artifacts/{artifact_id}

При использовании mount_beeui(parent, path="/ui") маршруты доступны под /ui/:

• GET /ui/
• GET /ui/health
• GET /ui/static/...
• GET /ui/runs/{run_id}/artifacts
• GET /ui/runs/{run_id}/artifacts/{artifact_id}
• GET /ui/api/runs/{run_id}/artifacts
• GET /ui/api/runs/{run_id}/artifacts/{artifact_id}

Iteration 11 добавляет только read-only artifact API routes. Stable BeeUI API для dashboard/runs/config/actions остаётся future scope.

Shell и dashboard рендерятся через component templates:

• components/sidebar.html;
• components/navbar.html;
• components/page_header.html;
• components/footer.html;
• components/empty_state.html.
• block component templates для literal и resolver-backed dashboard blocks.

Tabler-compatible vendor assets поставляются локально из package path:

• src/beeui_module/web/static/vendor/tabler/css/tabler-compatible.min.css
• src/beeui_module/web/static/vendor/tabler/js/tabler-compatible.min.js

BeeUI поставляет локальный Tabler-compatible subset в src/beeui_module/web/static/vendor/tabler/. Это не полный upstream Tabler demo bundle. Preview/demo/tracking assets не поставляются.

Navigation, theme и layout shell options (title/subtitle/paths/logo_text/theme/layout) рендерятся из config/schema.yml.

Пока не входит в scope:

• production BeeCap/BeeAgent adapters;
• adapter-backed dashboard/runs rendering (Iteration 12+);
• run detail page;
• stable BeeUI API для dashboard/runs/config/actions;
• auth/session;
• config UI;
• no-code builder.

Проект нужен, чтобы не писать заново в каждом продукте:

• web shell;
• sidebar / navbar / layout;
• dashboard;
• KPI cards;
• tables;
• artifact browser;
• config UI;
• operator/admin pages;
• theme customization;
• bounded operator actions;
• стабильный read-only JSON API для будущего frontend.

BeeUI строится как reusable layer поверх:

• FastAPI — web runtime;
• Jinja2 — server-rendered HTML templates;
• Tabler — UI/admin visual foundation;
• Pydantic / dataclasses — schema/config/read-model contracts;
• file/API adapters — подключение к Bee-продуктам.

BeeUI не является trading engine, agent runtime или backend core. Он не принимает domain-решения и не получает прямую execution authority.

Главное правило:

BeeUI renders.
Product decides.

Зачем нужен BeeUI

Сейчас beecap и beeagent начинают дублировать один и тот же UI-слой:

• разные web directories;
• разные templates;
• разные CSS;
• разные dashboards;
• разные artifact viewers;
• разные admin/config pages;
• разные operator controls.

Это быстро превращается в хаос.

BeeUI решает эту проблему как общий UI/runtime package:

beecap
  -> exposes read-model / artifacts / bounded actions
  -> BeeUI renders dashboard, runs, artifacts, config/admin pages

beeagent
  -> exposes modules / runs / capabilities / artifacts
  -> BeeUI renders operator console and будущий frontend shell

Текущий фокус проекта

Текущий фокус BeeUI:

• быстро дойти до MVP;
• подключить beecap как первый продукт;
• перестать расширять кастомный web UI внутри beecap;
• затем подключить beeagent;
• сохранить KISS, безопасность и read-only по умолчанию;
• подготовить основу для будущего no-code dashboard/frontend builder.

MVP не пытается сразу стать полноценным Retool/Webflow/Admin SaaS.

Целевой MVP делает controlled declarative console:

• pages описываются через schema/config;
• blocks описываются через schema/config;
• данные приходят из product adapter;
• artifacts отображаются через bounded artifact browser;
• write/control actions идут только через product-owned callbacks.

Что BeeUI делает

В текущем состоянии после Iteration 11 BeeUI отвечает за:

• FastAPI app factory;
• Jinja2 templates;
• Tabler layout;
• global navigation;
• reusable blocks;
• dashboard rendering;
• declarative pages/navigation/theme/layout;
• static/literal and resolver-backed dashboard blocks from config/schema.yml;
• generic product adapter contract v0 in src/beeui_module/adapters/;
• BeeCap-compatible fixture/reference adapter for contract validation;
• embedded app factory create_beeui_app(...);
• mount helper mount_beeui(...);
• загрузку product-specific UI config через config_path;
• product metadata injection;
• adapter injection, validation и сохранение в app.state.beeui_adapter;
• сохранение product metadata в app.state.beeui_product;
• проверку mount path и route collision guard;
• artifact browser — HTML/JSON list and preview через adapter;
• JSON/JSONL/text bounded preview с malformed handling, preview limits и redaction;
• read-only API routes для артефактов.

Запланированные обязанности:

• runs list / run detail pages;
• source artifact links;
• config read-model;
• config preview/apply framework;
• bounded operator actions;
• auth/session layer;
• theme customization;
• stable JSON API для будущего frontend;
• standalone mode.

Чего BeeUI не делает

BeeUI не должен:

• принимать торговые решения;
• запускать broker/API calls напрямую;
• читать secrets;
• менять runtime state без product callback;
• самостоятельно парсить domain logic BeeCap/BeeAgent;
• становиться вторым source of truth;
• заменять config/settings.yml продукта;
• заменять storage/ artifacts продукта;
• исполнять live/broker actions;
• делать hidden fallback execution;
• обходить product validation/security boundaries.

Все domain-sensitive вещи остаются в продукте.

Интеграционная модель

MVP: embedded mode

Для MVP BeeUI подключается как dependency внутрь продукта.

beecap process
  imports beeui
  creates BeeCapUiAdapter
  mounts BeeUI FastAPI app

Для BeeAgent это пока будущий scope. Целевая структура может быть похожей:

beeagent process
  imports beeui
  creates BeeAgentUiAdapter
  mounts BeeUI FastAPI app

Плюсы:

• быстро;
• один процесс;
• проще локальная разработка;
• проще auth/session;
• нет CORS;
• нет отдельного service discovery;
• меньше deployment complexity.

Минусы:

• каждый продукт запускает свой BeeUI instance;
• обновление BeeUI идёт через dependency update.

Будущий standalone mode

Позже BeeUI сможет работать отдельным сервисом:

beeui service
  -> connects to beecap API
  -> connects to beeagent API
  -> renders multi-product UI

Плюсы:

• один UI service;
• можно сделать unified Bee dashboard;
• проще отдельный frontend;
• можно держать beecap и beeagent как backend/API services.

Минусы:

• сложнее auth;
• CORS;
• network timeouts;
• service discovery;
• deployment complexity.

Решение:

MVP: embedded.
Позже: standalone.

Как подключать к BeeCap

На этапе разработки beeui лежит рядом:

~/Projects/
  beecap/
  beeagent/
  beeui/

В beecap/pyproject.toml для локальной разработки:

dependencies = [
    "beeui @ file:///home/bee/Projects/beeui",
]

Или временно:

cd ~/Projects/beecap
uv pip install -e ../beeui

Целевой вариант после стабилизации:

dependencies = [
    "beeui @ git+ssh://[e-mail]/beesyst/beeui.git@v0.1.0",
]

Минимальный integration point в BeeCap:

src/beecap_module/interfaces/ui/
  adapter.py
  read_model.py
  artifacts.py
  actions.py

BeeCap adapter отвечает за:

• dashboard read-model;
• runs list;
• run detail;
• artifact allowlist;
• artifact reading;
• config read-model;
• config validation callback;
• bounded action callbacks.

BeeUI не должен напрямую знать внутреннюю trading-логику BeeCap.

Как подключать к BeeAgent

BeeAgent integration — будущий scope. Ниже оставлена только минимальная целевая структура, чтобы не создавать впечатление готовой реализации.

Целевой integration point:

src/beeagent_module/interfaces/ui/
  adapter.py
  read_model.py
  artifacts.py
  capabilities.py
  actions.py

BeeAgent adapter отвечает за:

• dashboard read-model;
• modules;
• runs;
• artifacts;
• capabilities;
• approvals;
• bounded actions;
• authority/capability checks.

BeeUI не должен получать прямую authority на tools/MCP/runtime actions.

Режимы работы BeeUI

demo

Локальный demo mode.

Используется для разработки BeeUI без BeeCap/BeeAgent.

./start.sh web

Вариант с явным host/port:

./start.sh web --host 127.0.0.1 --port 8780

Что показывает:

• schema-driven demo pages;
• schema-driven navigation;
• schema-driven theme/layout;
• static/literal и resolver-backed dashboard blocks из config/schema.yml;
• controlled read-only demo data source;
• controlled read-only static YAML/JSON data source;
• empty state для pages без block placements.

embedded

Основное направление MVP integration.

Продукт импортирует BeeUI и монтирует его в своём web process.

Текущий статус после Iteration 11:

• generic adapter contract существует;
• BeeCap fixture/reference adapter существует для contract validation;
• production BeeCap adapter остаётся ответственностью BeeCap-side;
• create_beeui_app(...) accepts config_path, product metadata and adapter;
• mount_beeui(...) mounts BeeUI into parent FastAPI app;
• adapter is validated and stored in app.state.beeui_adapter;
• product metadata is stored in app.state.beeui_product;
• artifact browser routes уже используют adapter для list_artifacts() и read_artifact();
• /api/runs/{run_id}/artifacts* routes доступны при features.browser_artifact: true;
• adapter-backed dashboard/runs rendering остаётся future scope.

Embedded example:

from beeui_module.web.app import create_beeui_app
from beecap_module.interfaces.ui.adapter import BeeCapUiAdapter

app = create_beeui_app(
    product_id="beecap",
    product_title="BeeCap",
    adapter=BeeCapUiAdapter(...),
    config_path="config/beeui.yml",
)

standalone

Будущий scope.

В текущем MVP standalone mode не реализован. Запуск с отдельным config-файлом будет добавлен позже, когда появится HTTP product adapter и standalone deployment contract.

Основные возможности

Declarative pages

Страницы задаются через config/schema.

blocks:
  latest_run:
    type: metric_card
    title: Latest Run
    value: run_demo_001
    subtitle: Static demo value

pages:
  - id: dashboard
    path: /
    title: Dashboard
    subtitle: Demo operator dashboard
    blocks:
      - block: latest_run
        width: 3

Текущие declarative page rules:

• page.id must be unique;
• page.path must be unique;
• navigation[].path must reference declared page path;
• reserved paths /health, /static, /static/... are rejected;
• blocks in page config is a list of block placements;
• each placement references a top-level block id;
• width must be an integer from 1 to 12;
• unknown block references are rejected fail-fast.

Blocks

Текущий block contract после Iteration 7 поддерживает literal fields и resolver-backed fields из controlled read-only demo / static data sources.

Top-level blocks defines reusable block definitions. pages[].blocks[] defines where these blocks appear on a page.

Сейчас поддерживаются типы блоков:

• metric_card;
• kpi_grid;
• status_card;
• table_card;
• links_card;
• alert_card;
• text_card;
• progress_card.

Пример:

blocks:
  latest_run:
    type: metric_card
    title: Latest Run
    value: run_demo_001
    subtitle: Static demo value

  runtime_status:
    type: status_card
    title: Runtime
    status: ok
    value: Ready

pages:
  - id: dashboard
    path: /
    title: Dashboard
    subtitle: Demo operator dashboard
    blocks:
      - block: latest_run
        width: 3
      - block: runtime_status
        width: 3

Текущие правила:

• block ids must be safe identifiers;
• unknown block types are rejected;
• unknown block references are rejected;
• renderer-specific fields are validated fail-fast;
• text values are rendered through Jinja autoescape;
• no arbitrary HTML/JS/CSS from config;
• links_card.href accepts internal safe paths only;
• display values may be literal scalars or resolver-backed values from controlled demo/static sources;
• missing/empty page placements render an empty state.

Реализовано в Iteration 7:

• read-only data resolver;
• selector syntax with dot path and optional [index] lookup;
• demo source;
• static YAML/JSON source;
• stable resolver envelope;
• degraded block rendering on missing selector data.

Пока не реализовано:

• production BeeCap/BeeAgent adapters;
• adapter-backed block data in runtime;
• charts/maps;
• artifact/config/action blocks;
• arbitrary HTML/JS blocks.

Data sources

Iteration 7 поддерживает controlled read-only data sources в config/schema.yml. Текущие supported source types:

• demo
• static with format: yaml|json and a safe relative path

Resolver envelope:

{
  "status": "ok|partial|error",
  "data": {},
  "warnings": [
    {
      "code": "selector_missing",
      "message": "Selector not found: dashboard.latest_run.id"
    }
  ],
  "source": {
    "type": "demo|static|unknown",
    "id": "demo_dashboard"
  }
}

Текущая block schema остаётся backward-compatible: literal fields продолжают работать, resolver-backed fields опциональны. Adapter-backed data sources остаются будущим scope и не входят в текущие runtime source types Iteration 7.

Resolver-backed block example:

data_sources:
  demo_dashboard:
    type: demo

blocks:
  latest_run:
    type: metric_card
    title: Latest Run
    source: demo_dashboard
    value_selector: dashboard.latest_run.id
    subtitle_selector: dashboard.latest_run.status

Resolver envelope — внутренний block data-resolution contract в Iteration 7. Это ещё не public /api/* route contract. Public BeeUI JSON API запланирован для следующих итераций.

Product adapters

Product adapter contract реализован в Iteration 8 как generic boundary в src/beeui_module/adapters/.

Scope Iteration 8:

• generic ProductUiAdapter protocol/base contract;
• stable adapter envelopes for ok|partial|error;
• stable adapter error classes and error envelope helper;
• safe id validation helpers;
• optional write/action methods are disabled by default.

Non-goals Iteration 8:

• no production BeeCap adapter;
• no concrete BeeAgent adapter;
• no direct product filesystem crawling;
• public route surface не менялся в Iteration 8;
• no direct execution authority.

Iteration 9 добавляет BeeCap fixture/reference adapter support:

• BeeCapFixtureAdapter validates BeeCap-shaped dashboard/runs/artifact-reference payloads;
• fixtures live under tests/fixtures/beecap/;
• this adapter is not a production BeeCap integration;
• real BeeCap adapter must live on the BeeCap side under src/beecap_module/interfaces/ui/;
• Iteration 10 добавила app factory adapter injection и mount_beeui(...);
• Iteration 11 добавила adapter-backed artifact browser routes;
• adapter-backed dashboard/runs rendering остаётся future scope.

Текущий contract v0 после Iteration 8:

class ProductUiAdapter:
  # required read-only
  def get_dashboard(self) -> dict: ...
  def list_runs(self) -> dict: ...
  def get_run(self, run_id: str) -> dict: ...
  def list_artifacts(self, run_id: str) -> dict: ...
  def read_artifact(self, run_id: str, artifact_id: str) -> dict: ...
  def get_config_read_model(self) -> dict: ...

  # optional, unavailable by default
  def validate_config_candidate(self, candidate: dict) -> dict: ...
  def list_actions(self) -> dict: ...
  def preview_action(self, action_id: str, payload: dict) -> dict: ...
  def execute_action(self, action_id: str, payload: dict) -> dict: ...

После Iteration 11 BeeUI вызывает adapter через embedded mount/app factory layer для artifact browser routes.

Product adapter решает, что можно читать/делать.

Artifact browser

BeeUI предоставляет generic artifact browser после Iteration 11.

Он отображает:

• JSON;
• JSONL;
• text;
• metadata;
• parse warnings;
• source links;
• partial/corrupted state.

Правила:

• только allowlisted artifacts;
• никакого arbitrary filesystem browsing;
• path traversal заблокирован;
• source artifacts не мутируются;
• secrets redacted;
• corrupted artifacts не ломают page.

Routes:

GET /runs/{run_id}/artifacts
GET /runs/{run_id}/artifacts/{artifact_id}
GET /api/runs/{run_id}/artifacts
GET /api/runs/{run_id}/artifacts/{artifact_id}

Config UI

BeeUI должен дать reusable config UI layer, но не владеть config source of truth.

Source of truth остаётся в продукте:

beecap/config/settings.yml
beeagent/config/settings.yml

BeeUI config UI работает через product adapter.

Read-model

GET /config
GET /api/config/read-model

Показывает:

• editable fields;
• non-editable fields;
• redacted fields;
• current values;
• validation metadata;
• constraints/options.

Preview

POST /api/config/preview

Semantics:

• build candidate config in memory;
• call product validation callback;
• return diff + validation result;
• no file writes.

Apply

POST /api/config/apply

Semantics:

• only allowlisted keys;
• stale config hash guard;
• validate candidate through product validation callback;
• backup current config;
• write canonical product config;
• create audit artifact;
• no secrets in audit;
• no runtime restart hidden behind apply.

Suggested artifacts:

storage/interfaces/config_revisions/<change_id>/settings.before.yml
storage/interfaces/config_changes/<change_id>/audit.json

Operator actions

BeeUI can show bounded operator actions, but action execution belongs to the product.

Example actions:

• start allowed preset;
• refresh index;
• run doctor;
• create report;
• open artifact;
• create draft;
• approve safe internal action.

Forbidden by default:

• broker manual order;
• direct live execution;
• secret editing;
• arbitrary shell command;
• arbitrary config mutation;
• runtime kill/restart unless product explicitly exposes bounded callback.

All action attempts should create audit artifacts:

storage/interfaces/operator_actions/<action_id>.json

Auth and roles

BeeUI auth layer запланирован после MVP dashboard integration.

Initial roles:

Role	Meaning
viewer	read-only UI access
operator	read-only + bounded allowed actions
admin	config/admin actions inside allowlisted boundaries

Security rules:

• auth disabled only explicitly for local/dev;
• no default admin password in repo;
• password hash only;
• signed session cookies;
• CSRF protection for POST routes;
• no secrets in logs;
• no secrets in HTML/API.

Theme customization

BeeUI theme config:

app:
  theme:
    mode: dark
    primary: blue
    font: Inter
    radius: 2
    density: compact

Поддерживаемая кастомизация:

• dark/light;
• primary color;
• font family;
• border radius;
• density;
• product title;
• logo;
• favicon;
• compact mode.

Forbidden by default:

• arbitrary CSS editor;
• arbitrary JS;
• unsafe HTML injection;
• user-uploaded executable assets.

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

• Python 3.14+
• src-layout — пакет beeui_module в src/
• FastAPI — web runtime
• Jinja2 — templates
• Tabler — dashboard/admin UI foundation
• PyYAML — config/schema files
• pytest — тесты
• httpx — web route tests
• uv — dependency/install/runtime workflow
• file-based artifacts — для audits/examples/demo
• future: optional standalone HTTP adapter

Управление и запуск

Запуск — через start.sh.

Установка

После clone:

git clone [e-mail]:beesyst/beeui.git
cd beeui
./start.sh doctor

start.sh:

• проверяет наличие uv;
• если uv отсутствует — устанавливает его;
• ставит зависимости из uv.lock;
• запускает config/start.py;
• не должен скрыто менять runtime contracts.

Команды

./start.sh doctor

Проверяет:

• Python version;
• package import;
• config files;
• templates/static availability;
• basic environment.

./start.sh web

Запускает demo BeeUI web app.

./start.sh web --host 127.0.0.1 --port 8780

Запускает demo web app на конкретном host/port.

./start.sh routes

Показывает registered routes.

./start.sh version

Показывает версию BeeUI.

---

Локальная разработка

Установка зависимостей

uv sync --frozen --extra dev

Тесты

uv run pytest -q

Запуск demo UI

./start.sh web --host 127.0.0.1 --port 8780

Открыть:

http://127.0.0.1:8780

Без start.sh

uv run --frozen --extra dev python config/start.py doctor
uv run --frozen --extra dev python config/start.py web

Документация

Основная документация проекта находится в docs/.

Ключевые разделы:

• docs/ROADMAP.md — этапы и итерации;
• docs/SDLC.md — lightweight process, checks, PR workflow;
• docs/SECURITY.md — secure development rules;
• docs/WEB_UI.md — HTML routes, layout, dashboard behavior;

Целевая структура проекта

Актуальные ключевые файлы после Iteration 11:

config/
  settings.yml
  schema.yml

docs/
  INTEGRATION.md

examples/
  beecap_embedded/
    beeui.yml

tests/
  fixtures/
    beecap/

src/beeui_module/
  blocks/
    __init__.py
    models.py
    registry.py
    renderers.py
  cli/
    doctor.py
    main.py
    web.py
  core/
    paths.py
    settings.py
    log.py
    version.py
  data/
    __init__.py
    models.py
    resolver.py
    selectors.py
    sources.py
  adapters/
    __init__.py
    base.py
    envelopes.py
    errors.py
    ids.py
    beecap.py
  artifacts/
    __init__.py
    models.py
    preview.py
    redaction.py
    routes.py
  pages/
    config.py
    models.py
    router.py
  web/
    app.py
    templates/
      base.html
      page.html
      components/
        alert_card.html
        footer.html
        kpi_grid.html
        links_card.html
        metric_card.html
        navbar.html
        page_header.html
        progress_card.html
        sidebar.html
        status_card.html
        table_card.html
        text_card.html
        empty_state.html
      artifacts/
        list.html
        detail.html
    static/
      css/beeui.css
      js/beeui.js
      vendor/
        tabler/
          css/tabler-compatible.min.css
          js/tabler-compatible.min.js

Остальная структура ниже — целевая для следующих итераций.

beeui/
├── config/
│   ├── settings.yml
│   └── start.py
│
├── docs/
│   ├── API_CONTRACT.md
│   ├── COMPONENTS.md
│   ├── INTEGRATION.md
│   ├── ROADMAP.md
│   ├── SDLC.md
│   ├── SECURITY.md
│   ├── THEME.md
│   └── WEB_UI.md
│
├── examples/
│   ├── demo_static/
│   ├── beecap_embedded/
│   └── beeagent_embedded/
│
├── logs/
│   └── app.log
│
├── src/
│   └── beeui_module/
│       ├── __init__.py
│       ├── config.py
│       ├── errors.py
│       ├── server.py
│       ├── settings.py
│       │
│       ├── api/
│       │   ├── envelopes.py
│       │   └── routes.py
│       │
│       ├── artifacts/
│       │   ├── browser.py
│       │   ├── models.py
│       │   ├── readers.py
│       │   └── safe_paths.py
│       │
│       ├── auth/
│       │   ├── models.py
│       │   ├── password.py
│       │   ├── permissions.py
│       │   ├── routes.py
│       │   ├── service.py
│       │   └── sessions.py
│       │
│       ├── adapters/
│       │   ├── base.py
│       │   ├── filesystem.py
│       │   ├── http.py
│       │   ├── product.py
│       │   ├── beecap.py
│       │   └── beeagent.py
│       │
│       ├── blocks/
│       │   ├── models.py
│       │   ├── registry.py
│       │   ├── renderers.py
│       │   └── types/
│       │       ├── artifact_table.py
│       │       ├── chart_card.py
│       │       ├── json_viewer.py
│       │       ├── kpi_grid.py
│       │       ├── links_card.py
│       │       ├── metric_card.py
│       │       ├── status_card.py
│       │       └── table_card.py
│       │
│       ├── cli/
│       │   ├── doctor.py
│       │   ├── main.py
│       │   └── web.py
│       │
│       ├── config_ui/
│       │   ├── apply.py
│       │   ├── audit.py
│       │   ├── preview.py
│       │   ├── read_model.py
│       │   └── routes.py
│       │
│       ├── core/
│       │   ├── ids.py
│       │   ├── json.py
│       │   ├── logging.py
│       │   ├── paths.py
│       │   └── security.py
│       │
│       ├── data/
│       │   ├── envelopes.py
│       │   ├── resolver.py
│       │   ├── selectors.py
│       │   └── sources.py
│       │
│       ├── pages/
│       │   ├── models.py
│       │   ├── registry.py
│       │   ├── renderer.py
│       │   └── router.py
│       │
│       ├── web/
│       │   ├── __init__.py
│       │   ├── app.py
│       │   ├── templates/
│       │   │   ├── base.html
│       │   │   └── page.html
│       │   └── static/
│       │       ├── css/
│       │       │   └── beeui.css
│       │       └── js/
│       │           └── beeui.js
│       │
│       └── theme/
│           ├── css.py
│           ├── models.py
│           └── service.py
│
├── tests/
│   ├── test_adapters.py
│   ├── test_app.py
│   ├── test_artifacts.py
│   ├── test_blocks.py
│   ├── test_config.py
│   ├── test_pages.py
│   ├── test_security.py
│   └── test_smoke.py
│
├── pyproject.toml
├── README.ru.md
├── start.sh
└── uv.lock

Архитектура

1. App/Web layer

Отвечает за:

• FastAPI app factory;
• templates/static;
• routes;
• global layout;
• API routes;
• error pages.

Ключевые модули:

src/beeui_module/web/app.py
src/beeui_module/web/templates/
src/beeui_module/web/static/

Planned after Iteration 2:

src/beeui_module/server.py
src/beeui_module/pages/

2. Adapter layer

Отвечает за подключение к продуктам.

src/beeui_module/adapters/

Типы adapters:

• ProductUiAdapter — base contract;
• BeeCapUiAdapter — BeeCap-specific read-model adapter;
• BeeAgentUiAdapter — BeeAgent-specific read-model adapter;
• HttpProductAdapter — будущий standalone mode;
• FilesystemAdapter — demo/local artifact reading.

3. Data resolver layer

Отвечает за:

• source lookup;
• selector resolution;
• partial data;
• warnings/errors;
• normalized envelopes.

src/beeui_module/data/

4. Blocks layer

Отвечает за reusable UI blocks.

src/beeui_module/blocks/
src/beeui_module/web/templates/components/

5. Artifact layer

Отвечает за safe artifact navigation.

src/beeui_module/artifacts/

Security responsibilities:

• artifact allowlist;
• safe IDs;
• path traversal guard;
• JSON/JSONL tolerant parsing;
• redaction;
• no mutation.

6. Config UI layer

Отвечает за:

• config read-model;
• preview;
• apply;
• audit;
• backup.

src/beeui_module/config_ui/

Важно:

• product config remains source of truth;
• product validation callback is mandatory for apply;
• BeeUI does not invent config semantics.

7. Auth layer

Planned layer.

src/beeui_module/auth/

Отвечает за:

• users;
• sessions;
• roles;
• permissions;
• CSRF;
• route protection.

JSON API contract

BeeUI API должен использовать единый envelope. Resolver envelope is an internal block data-resolution contract in Iteration 7. It is not yet a public /api/* route contract. Public BeeUI JSON API запланирован для следующих итераций.

Success

{
  "ok": true,
  "status": "ok",
  "data": {},
  "warnings": [],
  "meta": {
    "source": "adapter",
    "product": "beecap"
  }
}

Partial

{
  "ok": true,
  "status": "partial",
  "data": {},
  "warnings": [
    {
      "code": "artifact_missing",
      "message": "health.json is missing"
    }
  ],
  "meta": {
    "source": "adapter",
    "product": "beecap"
  }
}

Error

{
  "ok": false,
  "status": "error",
  "error": {
    "code": "invalid_run_id",
    "message": "Invalid run_id"
  },
  "warnings": [],
  "meta": {
    "source": "beeui"
  }
}

Planned routes

HTML

GET /
GET /runs
GET /runs/{run_id}
GET /runs/{run_id}/artifacts
GET /config
GET /admin
GET /login
GET /logout

API

GET /api/dashboard
GET /api/runs
GET /api/runs/{run_id}
GET /api/runs/{run_id}/artifacts
GET /api/runs/{run_id}/artifacts/{artifact_id}
GET /api/config/read-model
POST /api/config/preview
POST /api/config/apply
GET /api/actions
POST /api/actions/{action_id}

Routes can be mounted under prefix:

/ui
/console
/admin

depending on product integration.

Безопасность

BeeUI находится на trust boundary, потому что отображает:

• configs;
• artifacts;
• operator actions;
• diagnostics;
• product state;
• potential admin controls.

Правила безопасности:

• read-only by default;
• all IDs are untrusted input;
• path traversal guard everywhere;
• HTML autoescape enabled;
• no arbitrary HTML/JS blocks;
• artifact access allowlisted;
• config write allowlisted;
• action execution product-owned;
• secrets redacted in HTML/API/logs/audits;
• POST routes protected by CSRF when auth enabled;
• no direct broker/runtime authority;
• no hidden fallback from denied action to allowed action;
• no automatic runtime restart after config apply.

Особо запрещено:

• отдавать .env;
• отдавать raw secret values;
• читать arbitrary path из query param;
• делать direct shell commands из UI;
• делать live broker calls из BeeUI;
• писать runtime artifacts без product-owned action callback.

MVP roadmap summary

Критический путь к MVP:

Iteration 0 — Project skeleton and startup contract
Iteration 1 — Tabler web shell v0
Iteration 2 — Declarative pages and navigation v0
Iteration 3 — Local Tabler vendor/assets and layout parity v1
Iteration 4 — Theme, layout and navigation schema v1
Iteration 5 — Block registry and static dashboard blocks v1
Iteration 7 — Data sources and resolver v0
Iteration 8 — Product adapter contract v0
Iteration 9 — BeeCap adapter MVP
Iteration 10 — Embedded mount API v0
Iteration 11 — Generic artifact browser v1
Iteration 12 — BeeCap dashboard parity MVP
Iteration 13 — Runs list and run overview MVP

MVP считается достигнутым, если:

• beeui запускается отдельно как demo;
• beeui подключается к beecap;
• BeeCap dashboard рендерится через BeeUI;
• BeeCap current custom templates больше не расширяются вручную;
• run list / run detail / artifact links работают;
• UI read-only по умолчанию;
• tests green.

Что должно остаться в BeeCap/BeeAgent после внедрения BeeUI

Bee-продукты сохраняют:

• core runtime;
• config validation;
• product artifacts;
• product read-model;
• domain-specific summaries;
• bounded actions;
• authority/security checks.

Bee-продукты больше не должны дублировать:

• base web shell;
• Tabler layout;
• sidebar/navbar;
• reusable KPI cards;
• generic tables;
• generic artifact browser;
• theme layer;
• common config UI;
• common admin/support pages.

Диагностика и тесты

Диагностика

Команда	Что делает
./start.sh doctor	Проверка окружения, структуры, imports, config availability
./start.sh web	Запуск demo BeeUI web app
./start.sh routes	Показ registered routes
./start.sh version	Показ версии BeeUI

Тесты

uv run pytest -q

Web smoke

./start.sh web --host 127.0.0.1 --port 8780

Проверить:

http://127.0.0.1:8780/
http://127.0.0.1:8780/health

Security smoke

Проверить:

• no secrets in HTML;
• no secrets in API;
• invalid run_id rejected;
• path traversal rejected;
• POST routes do not work without explicit implementation;
• static files limited to BeeUI static directory.

Deployment

MVP deployment

Embedded per product.

container: beecap
  includes beeui dependency
  exposes beecap web

container: beeagent
  includes beeui dependency
  exposes beeagent web

Плюсы:

• проще;
• меньше сетевых связей;
• быстрее MVP;
• меньше auth/CORS проблем.

Будущий deployment

Standalone BeeUI.

container: beeui
container: beecap-api
container: beeagent-api

Использовать только после стабилизации:

• BeeUI API contracts;
• product APIs;
• auth/session model;
• deployment model.

Важно

BeeUI — это не просто UI kit.

Правильное определение:

BeeUI is a reusable UI/runtime framework for Bee products.

Он должен развиваться от простого embedded UI package к platform layer:

1. server-rendered operator console;
2. reusable dashboard blocks;
3. artifact/config/admin views;
4. stable JSON API;
5. auth/RBAC;
6. bounded operator controls;
7. будущий no-code dashboard builder;
8. будущий standalone frontend backend.

Неправильное направление:

Сразу делать no-code Retool/Webflow clone.

Это приведёт к месячной разработке без MVP.

Правильное направление:

Declarative schema first.
Visual builder later.

Текущий статус

Проект создан как отдельная repo:

~/Projects/beeui

Текущий статус:

Iteration 11 — Generic artifact browser v1 — DONE

Работает:

./start.sh doctor
./start.sh routes
uv run pytest -q
./start.sh web --host 127.0.0.1 --port 8780

• / рендерит literal и resolver-backed dashboard blocks from schema;
• /runs рендерит empty state для страницы без block placements;
• /components* рендерит internal read-only catalog of controlled primitives;
• resolver-backed blocks читают значения из controlled read-only demo / static sources;
• missing selector data рендерит degraded/error block state вместо падения страницы;
• generic ProductUiAdapter contract доступен в src/beeui_module/adapters/;
• optional adapter write/action methods недоступны по умолчанию;
• BeeCapFixtureAdapter валидирует BeeCap-shaped fixture payloads;
• BeeCap-like fixtures покрывают dashboard, runs, artifact references, partial и corrupted artifact states;
• integration boundary задокументирован в docs/INTEGRATION.md;
• create_beeui_app(...) accepts config_path, product metadata and adapter;
• mount_beeui(...) mounts BeeUI into parent FastAPI app;
• adapter is validated and stored in app.state.beeui_adapter;
• product metadata is stored in app.state.beeui_product;
• artifact browser HTML/API routes работают через adapter;
• /api/runs/{run_id}/artifacts* routes доступны при features.browser_artifact: true;
• adapter-backed dashboard/runs rendering остаётся future scope.