Registry File DB

File-based storage backend for the BSB Registry. Stores all data as JSON files in a configurable directory. This is the default storage backend -- suitable for development, single-instance deployments, and small registries.

Configuration

service-bsb-registry:
  database:
    type: file
    path: ./.temp/data

The path is the root directory. All subdirectories and files are created automatically on first startup.

Directory Layout

<path>/
  plugins/
    <org>/
      <name>/
        <version>.json          # RegistryEntry for each published version
  orgs/
    <orgId>.json                # Organization metadata + members
  users.json                    # User[] array
  tokens.json                   # AuthToken[] array

File Schemas

Plugin Version -- plugins/<org>/<name>/<version>.json

One file per published version. Created on publish, never modified (versions are immutable).

{
  "id": "mycompany/service-demo",
  "org": "mycompany",
  "name": "service-demo",
  "displayName": "Demo Service",
  "description": "Example service plugin",
  "version": "1.0.0",
  "majorMinor": "1.0",
  "language": "nodejs",
  "category": "service",
  "tags": ["demo", "example"],
  "visibility": "public",
  "eventSchema": {
    "demo.do-something": {
      "type": "returnable",
      "category": "onReturnableEvents",
      "description": "Does something",
      "inputSchema": { "type": "object", "properties": {} },
      "outputSchema": { "type": "object", "properties": {} }
    }
  },
  "configSchema": {
    "type": "object",
    "properties": {
      "port": { "type": "number", "default": 3000, "description": "Server port" }
    },
    "required": ["port"]
  },
  "documentation": [
    "# Demo Service\n\nMain documentation content..."
  ],
  "dependencies": [],
  "package": {
    "nodejs": "@mycompany/service-demo"
  },
  "runtime": {
    "nodejs": ">=18.0.0"
  },
  "author": {
    "name": "Author Name",
    "email": "author@example.com"
  },
  "license": "MIT",
  "homepage": "https://example.com",
  "repository": "https://github.com/mycompany/service-demo",
  "eventCount": 1,
  "emitEventCount": 0,
  "onEventCount": 0,
  "returnableEventCount": 1,
  "broadcastEventCount": 0,
  "publishedBy": "user-uuid-here",
  "publishedAt": "2026-02-17T00:00:00.000Z",
  "updatedAt": "2026-02-17T00:00:00.000Z",
  "downloads": 0
}

Field Reference

Organization -- orgs/<orgId>.json

One file per organization. Created when an organization is first set up.

{
  "id": "mycompany",
  "name": "mycompany",
  "displayName": "My Company",
  "pluginCount": 0,
  "visibility": "public",
  "members": [
    {
      "userId": "user-uuid-here",
      "permission": "write"
    }
  ]
}

Member permissions: read or write.

Users -- users.json

Single file containing all registered users as a JSON array.

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Admin User",
    "email": "admin@example.com",
    "active": true,
    "permissions": ["read", "write", "create-org"],
    "createdAt": "2026-02-17T00:00:00.000Z",
    "updatedAt": "2026-02-17T00:00:00.000Z"
  }
]

Tokens -- tokens.json

Single file containing all API tokens as a JSON array.

[
  {
    "token": "bsb_abc123...",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "CI deploy",
    "permissions": ["read", "write"],
    "createdAt": "2026-02-17T00:00:00.000Z",
    "expiresAt": null
  }
]

Bootstrapping

On first startup, the file DB creates the directory structure and empty users.json / tokens.json files automatically. No manual setup is needed.

To seed initial data, create the files manually before starting the service:

1. Create users.json with at least one admin user
2. Create tokens.json with a token tied to that user
3. Start the service -- it will use the existing files

Generate a token string:

node --input-type=module -e "import { randomBytes } from 'node:crypto'; console.log('bsb_' + randomBytes(32).toString('hex'));"

Limitations

• Single-writer only -- no concurrent process safety
• All queries scan files on disk (no indexing)
• Not suitable for large registries (1000+ plugins)
• No automatic backups -- back up the data directory yourself

For production or multi-instance deployments, use PostgreSQL (database.type: postgres).

See Also

• service-bsb-registry -- Core registry plugin
• service-bsb-registry-ui -- Web UI and REST API