BSB Registry UI & API

Web interface and REST API for the BSB plugin registry. Serves both HTML (server-side rendered with Handlebars) and JSON from the same routes using content negotiation.

This plugin communicates with service-bsb-registry (the core) via BSB events -- not HTTP. Both plugins can run in the same process or across distributed services.

Configuration

service-bsb-registry-ui:
  port: 3200                     # single HTTP port for UI + API
  host: 0.0.0.0
  pageSize: 20                   # plugins per page in browse view
  uploadDir: ./.temp/registry-images
  badgesFile: ./BADGES.json
  maxImageUploadMb: 5

Content Negotiation

Every route serves either HTML or JSON based on the Accept header:

This means the CLI, CI/CD tools, and the web browser all use the same URL paths.

Routes

Public (Read)

Authenticated (Write)

Authentication is via Authorization: Bearer {token} header.

Query Parameters

Browse (/plugins):

Docs (/plugins/:org/:name/:version/docs):

Web UI Features

Browse Page

• Plugin cards with name, description, version, category badge, language tags
• Full-text search across names, tags, and descriptions
• Filter by category and language
• Pagination with configurable page size
• Registry statistics header (total plugins, languages, downloads)

Plugin Detail Page

• Plugin metadata (version, category, author, license, links)
• Installation instructions with copy-paste commands
• Configuration properties (from JSON Schema, with types, defaults, descriptions)
• Event schema (collapsible list with name, type badge, description; expand for input/output schemas)
• Tabbed documentation (each markdown file becomes a tab, title from first # heading)
• Dependencies list

Design

• Dark theme matching BSB documentation site
• Responsive layout (desktop, tablet, mobile)
• Server-side rendered (no client-side JS framework)
• Static CSS with CSS custom properties for theming

Publishing via API

curl -X POST http://localhost:3200/plugins \
  -H "Authorization: Bearer bsb_your_token" \
  -H "Content-Type: application/json" \
  -d @publish-payload.json

See service-bsb-registry.md for the full publish request schema.

Plugin Badges

Create a BADGES.json file to force specific badges:

{
  "bettercorp/config-default": ["CORE", "OFFICIAL"],
  "bettercorp/events-rabbitmq": "OFFICIAL"
}

Badge fallback order:

1. Entry in BADGES.json
2. Organization name (for org/name plugins)
3. COMMUNITY

How It Works

1. Browser requests a page (e.g. GET /plugins/myorg/my-plugin)
2. UI server validates route params with Zod
3. UI server emits a BSB event (e.g. registry.plugin.get) via the generated BsbRegistryClient
4. Core plugin processes the event and returns data
5. UI server renders a Handlebars template with the data (or returns JSON if Accept: application/json)
6. Response is sent to the browser

This architecture means the UI has zero direct database access. Swapping events-default for events-rabbitmq makes it distributed with no code changes.

Development

Project Structure

src/plugins/service-bsb-registry-ui/
  index.ts              Plugin entry point (config, lifecycle)
  http-server.ts        Fastify server, routes, Zod validation, rendering
  templates/
    layouts/
      main.hbs          Base HTML layout
    pages/
      browse.hbs        Plugin list / search results
      plugin-detail.hbs Plugin detail page
  static/
    css/
      style.css         All styles

Build

npm run build           # compiles TS + copies static assets and templates

Templates and static files are copied from src/ to lib/ during build.

Customization

Edit files in src/plugins/service-bsb-registry-ui/:

• static/css/style.css -- all styles (CSS custom properties for colors)
• templates/pages/*.hbs -- page templates
• http-server.ts -- routes and data processing

Rebuild and restart after changes.

Deployment

Behind Reverse Proxy

Since both UI and API are on the same port, a single proxy rule is sufficient:

server {
    listen 443 ssl http2;
    server_name registry.example.com;

    location / {
        proxy_pass http://localhost:3200;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

See Also

• service-bsb-registry -- Core registry (events, storage, auth, publish schema)
• BSB Registry README -- Project overview