Hub Database Architecture

Purpose

Hub now serves Dock entries from a local SQLite catalog instead of reading runtime data directly from one large TypeScript array.

This keeps the runtime fast and searchable while still letting us seed the catalog from curated JSON source files.

Why SQLite

• local-first and simple to ship with the Hub service
• fast enough for catalog, action, and workflow metadata at Harbor's current scale
• supports FTS5 for action-level and integration-level search
• easy to keep modular without introducing cloud-only infrastructure into Hub

Current source split

• Seed content lives in catalog
• Integration documents live under integrations
• Future workflow bundle documents live under workflows
• Runtime repository functions live in catalog.ts
• Filesystem loading lives in catalog-loader.ts
• SQLite schema, seeding, and search logic live in hub-store.ts

Schema shape

Hub stores:

• publishers
• integrations
• integration aliases
• integration tags
• port templates
• action templates
• workflows
• workflow action refs for future multi-port workflow composition

Hub also maintains FTS tables for:

• integration search
• action search

Runtime endpoints

The database-backed Hub keeps the existing import-safe endpoints stable:

• GET /api/integrations
• GET /api/integrations/:publisher/:slug
• GET /api/manifests/:publisher/:slug
• GET /api/resolve/:shortcut

New search and shelf endpoints:

• GET /api/shelves
• GET /api/actions/search

Environment

Default: file:./data/hub.db

• HUB_DATABASE_URL

Deployment rule

• Native Hub runs should keep hub.db in the app-local data/ folder.
• Docker Hub runs should keep hub.db under the Hub service volume, currently /data/hub.db in harbor-hub.
• Hub's SQLite database is part of the Dock service boundary, so it should not be modeled as a separate standalone database container unless Hub later moves to a true server database like Postgres.

Next steps

• add workflow bundle JSON records that reference actions across multiple integrations
• add real popularity or like signals instead of the current seeded ranking defaults
• optionally add validation tooling for integration and workflow JSON documents