@novahelm/platform

Multi-tenant platform engine for NovaHelm — project management, schema builder, DDL engine, module system, backup engine, platform sync, and 60+ tRPC routers powering the NovaHelm Console.

Quick Start

pnpm add @novahelm/platform

import { initPlatformResolver, createProjectStore, createDbManager } from "@novahelm/platform";

// Wire project-scoped DB resolution into the registry
initPlatformResolver();

// Create the project store (LRU cache of project connections)
const store = createProjectStore({ maxProjects: 50 });

// Create the DB manager (create, migrate, seed, backup, restore)
const dbManager = createDbManager({ adminDatabaseUrl: "postgres://..." });

Schema Builder (DDL Engine)

Dashboard admins can design tables via UI. The DDL engine generates and executes Postgres DDL:

import {
  generateCreateTableDDL,
  generateAddColumnDDL,
  generateSearchVectorDDL,
  FIELD_TYPES,
} from "@novahelm/platform";

// 18 field types: text, number, boolean, relation, json, date, etc.
const ddl = generateCreateTableDDL("blog_posts", [
  { name: "title", type: "text", required: true, searchable: true },
  { name: "body", type: "richtext", searchable: true },
  { name: "published", type: "boolean", defaultValue: "false" },
]);

// Adds ALTER TABLE for new columns
const alterDdl = generateAddColumnDDL("blog_posts", {
  name: "category",
  type: "text",
  indexed: true,
});

Module System

Register, load, and manage modules with typed extension points:

import {
  registerModule,
  loadModuleExtensions,
  getModuleRouters,
  getModuleNavItems,
  getModulePages,
} from "@novahelm/platform";

// Register all built-in and standalone modules at startup
import { registerAllModules } from "@novahelm/platform";
registerAllModules();

// Load a module's extension points (routers, nav, schema, workers, etc.)
await loadModuleExtensions("project-docs");

// Query aggregated extensions
const routers = getModuleRouters();
const navItems = getModuleNavItems();

Project Scoping

Run code in a project-scoped context where getDb() and getConfig() return project-specific instances:

import { runInProjectScope, getCurrentProject } from "@novahelm/platform";

await runInProjectScope(projectContext, async () => {
  const project = getCurrentProject(); // typed ProjectContext
  const db = getDb(); // returns project-scoped DB
  await db.select().from(posts);
});

Backup Engine

Full backup and restore with encryption, checksums, and retention policies:

import {
  executeDatabaseBackup,
  executeDatabaseRestore,
  pruneRetention,
  DEFAULT_RETENTION_POLICY,
} from "@novahelm/platform";

const result = await executeDatabaseBackup({
  databaseUrl: "postgres://...",
  destinationClient: s3Client,
  encryptionKey: "...",
});

// Prune old backups according to retention tiers
await pruneRetention(db, projectId, DEFAULT_RETENTION_POLICY);

Key Exports

| Category | Exports | |----------|---------| | Init | initPlatformResolver() | | Schema | projects, platformUsers, customTables, projectModules, 30+ table exports | | DDL | generateCreateTableDDL, generateAddColumnDDL, generateAlterColumnDDL, generateSearchVectorDDL, FIELD_TYPES | | Modules | registerModule, loadModuleExtensions, getModuleRouters, getModuleNavItems, getModulePages, reviewModule | | Scoping | runInProjectScope, getCurrentProject, createProjectStore, createScopedEnqueue | | Backup | executeDatabaseBackup, executeDatabaseRestore, executeStorageBackup, pruneRetention | | Auth | createPlatformAuth, hashPassword, verifyPassword | | Env | encryptValue, decryptValue, rotateEncryptionKey | | Sync | handlePlatformSyncRequest, compareVectorClocks, mergeVectorClocks | | Routers | 60+ create*Router factory functions for the Console tRPC API | | Services | registerBuiltinServices, defineService, listServices | | Git | initRepo, commitFiles, listBranches, listCommits, getFileTree | | Hosting | addSite, removeSite, updateSite, checkDns, getSslStatus |