smrt

s-m-r-t framework

Define business objects once. Use them through persistence, REST, CLI, MCP, agents, web clients, and native apps.

s-m-r-t is a TypeScript framework for building operational software and vertical AI agents around the same typed domain model. Decorated classes become manifest-described objects with portable persistence, generated interfaces, tenant-aware relationships, AI operations, and reusable domain packages.

It is designed for systems where the difficult part is keeping data, permissions, tools, background work, user interfaces, and automation aligned as the domain grows—not merely implementing one endpoint or agent prompt. The repository contains 61 top-level platform packages published primarily under @happyvertical/smrt-*, plus a private playground test-host workspace.

Define once, expose deliberately

flowchart LR
  A["TypeScript classes with @smrt()"] --> B["Manifest and schema metadata"]
  B --> C["SQLite, PostgreSQL, or DuckDB"]
  B --> D["REST and typed clients"]
  B --> E["CLI, MCP, and WebMCP tools"]
  B --> F["Web and mobile collections"]
  C --> G["Agents, jobs, and domain services"]
  D --> G
  E --> G
  F --> G

Generation is allowlist-driven. A model does not become publicly writable just because it exists: each @smrt() declaration controls its REST, CLI, MCP, AI, cache, tenancy, and lifecycle surface.

Requirements

• Node.js 26 or newer
• pnpm 11.13.1 or newer (11.13.0 is a broken release pnpm itself refuses)
• A supported database adapter (SQLite is convenient for local development; PostgreSQL and DuckDB are supported where documented)

Quick start

pnpm init
pnpm pkg set type=module
pnpm add @happyvertical/smrt-config @happyvertical/smrt-core
pnpm add --save-dev @happyvertical/smrt-cli @types/node vite typescript
mkdir -p src

Save this as src/product.ts:

import { ObjectRegistry, SmrtCollection, SmrtObject, smrt } from '@happyvertical/smrt-core';

ObjectRegistry.registerPackageManifest(
  new URL('../.smrt/manifest.json', import.meta.url),
);

@smrt({ api: true, cli: true, mcp: true })
export class Product extends SmrtObject {
  name: string = '';
  price: number = 0.0; // decimal schema field
  quantity: number = 0; // integer schema field
}

export class ProductCollection extends SmrtCollection<Product> {
  static readonly _itemClass = Product;
}

const database = {
  type: 'sqlite' as const,
  url: process.env.DATABASE_URL ?? 'products.db',
};
const products = await ProductCollection.create({ db: database, persistence: database });
const product = await products.create({
  name: 'Field Recorder',
  price: 299.99,
  quantity: 4,
});
await product.save();

Configure the supported build-time scanner in vite.config.ts:

import { smrtPlugin } from '@happyvertical/smrt-core/vite-plugin';
import { defineConfig } from 'vite';

export default defineConfig({
  oxc: { decorator: { legacy: true, emitDecoratorMetadata: true } },
  plugins: [smrtPlugin({ include: ['src/**/*.ts'] })],
});

Configure the CLI database in smrt.config.ts (the db:* commands read packages.cli.database; they do not read DATABASE_* directly):

import { defineConfig } from '@happyvertical/smrt-config';

export default defineConfig({
  packages: {
    cli: {
      database: {
        type: 'sqlite',
        url: process.env.DATABASE_URL ?? 'products.db',
      },
    },
  },
});

Generate the manifest, apply its schema to the fresh SQLite database, and only then run the example. The example explicitly registers that generated application manifest before creating the collection:

DATABASE_URL=products.db pnpm vite build --ssr src/product.ts
DATABASE_URL=products.db pnpm smrt db:migrate
DATABASE_URL=products.db node dist/product.js

Running the built dist/product.js entry preserves the manifest-registration call in the executable output, where its ../.smrt/manifest.json URL resolves to the manifest generated by the scanner. @smrt() makes the class discoverable to that build-time scanner. Enabling api, cli, and mcp declares generated surfaces. smrt db:migrate is the supported manifest-driven setup and migration path; runtime initialization verifies application schema rather than creating it implicitly.

For framework invariants and production setup, read the repository guide and the core package documentation.

Platform capabilities

• Domain-first ORM: typed objects, collections, relationships, tenancy, STI, migrations, and portable database adapters.
• Generated interfaces: REST, CLI, MCP, manifests, web collection definitions, and mobile contracts from one model graph.
• AI runtime: object-level is()/do(), prompts, agents, personas, learning memory, jobs, and observability signals.
• Reusable vertical packages: identity, content, commerce, sales, support, projects, media, analytics, and more.
• Cross-platform clients: Svelte 5 UI, browser data runtime, Kotlin Multiplatform foundations, Android Compose, and SwiftUI.

Choose your path

Goal	Start here
Learn the object and collection model	smrt-core
Start a SvelteKit application	smrt-template-sveltekit
Run a local, self-hosted, or cloud application	smrt-app-runtime
Build agents and personas	smrt-agents, smrt-personas
Add tenant-aware identity and authorization	smrt-tenancy, smrt-users
Build live or offline browser data	smrt-web, smrt-svelte
Expose an application CLI or MCP server	smrt-app-cli, smrt-app-mcp
Use an existing business domain	Browse the linked package catalog below
Extend or review the framework	AGENTS.md, smrt-dev-mcp

Package catalog

Status legend:

• Stable — established public package contract.
• Preview — public and usable, with an actively evolving contract.
• Experimental — incomplete or exploratory; evaluate before production use.
• Internal — repository tooling or platform package, not a general npm API.
• Deprecated — compatibility only; follow its migration guide.

Foundation and tooling

Package	Status	Purpose
smrt-core	Stable	ORM, decorators, registries, code generation, AI operations, and runtime services.
smrt-types	Stable	Shared framework types and enums.
smrt-config	Stable	Configuration loading, validation, redaction, and static export.
smrt-scanner	Stable	OXC-based TypeScript metadata scanner.
smrt-tenancy	Stable	Tenant context, interceptors, and isolation adapters.
smrt-vitest	Stable	Manifest-aware Vitest integration and database isolation.
smrt-cli	Stable	Developer CLI, schema commands, generation, and knowledge tooling.
smrt-app-cli	Preview	Reusable branded application CLI and stdio MCP bridge.
smrt-app-runtime	Preview	Validated local, self-hosted, and cloud composition with safe bootstrap, provider diagnostics, and profile-selected workers.
smrt-workbench	Preview	CWD-scoped package and project workbench for docs, APIs, routes, previews, and knowledge.
smrt-workbench-host	Internal	Private SvelteKit browser host bundled with the workbench package.
smrt-dev-mcp	Stable	Development MCP server and repository knowledge tools.
smrt-app-mcp	Preview	App-runtime MCP server and transport adapters.
smrt-mcp-apps	Preview	Portable browser bridge for embedded MCP Apps with bounded host messaging and lifecycle controls.
smrt-mcp-openai	Preview	Optional OpenAI navigation, settings, display, and onboarding adapter.
smrt-mcp-conformance-fixture	Internal	Generated Tier-1 MCP 2026-07-28 conformance gate.
smrt-bundle-gate	Internal	Consumer bundle reachability and size regression gate.

Agents, identity, and operations

Package	Status	Purpose
smrt-agents	Stable	Agent lifecycle, discovery, dispatch, and scheduling.
smrt-jobs	Stable	Durable background jobs, task runners, and schedules.
smrt-users	Stable	Users, tenants, sessions, RBAC, permissions, and RLS.
smrt-profiles	Stable	Identity profiles, authentication bindings, and relationships.
smrt-personas	Preview	Context-scoped agent personas and governed learning loop.
smrt-approvals	Experimental	Revision-bound, single-use approvals with quorum, expiry, and an append-only decision ledger.
smrt-playbooks	Preview	Layered playbook registry, overrides, and plan resolution.
smrt-prompts	Stable	Typed prompt registry and tenant-aware overrides.
smrt-projects	Preview	Provider-neutral projects, repositories, issues, and delivery work.
smrt-support	Preview	Support Case intake, lifecycle, routing, targets, and service time.
smrt-timesheets	Preview	Shared time entries, approval and correction, and immutable charge/compensation snapshots.
smrt-human-resources	Preview	Employment records with dated terms, and qualifications with expiry.

Content and media

Package	Status	Purpose
smrt-content	Stable	Versioned content, documents, mirrors, thumbnails, and citations.
smrt-assets	Stable	Provider-neutral asset identity, versions, metadata, and lineage.
smrt-assets-local	Preview	Local image metadata and deterministic variant processing.
smrt-assets-ergot	Preview	Ergot processing, search, workflow, and synchronization adapter.
smrt-images	Stable	Image categorization, editing, search, and asset extensions.
smrt-ingestion	Experimental	Durable intake, evidence revisions, stage recovery, and action journal foundations.
smrt-video	Stable	Video production models, scenes, performers, and workflows.
smrt-voice	Stable	Voice profiles, synthesis, cloning, and word timing.
smrt-messages	Stable	Provider-neutral multi-channel messages and credentials.
smrt-chat	Stable	Rooms, DMs, threads, sessions, and agent conversations.
smrt-comments	Preview	Record comments and mention notification hooks.
smrt-reactions	Experimental	Guarded reactions and polls for SQLite and PostgreSQL.
smrt-webhooks	Preview	Signed outbound webhooks, durable retries, and delivery administration.
smrt-social	Stable	Social account OAuth, publishing, and scheduling.

Business and domain

Package	Status	Purpose
smrt-commerce	Stable	Customers, vendors, contracts, invoices, and fulfillment.
smrt-products	Stable	Product catalog and triple-consumption package template.
smrt-sales	Preview	Agreements, CRM, referrals, commissions, and sales surfaces.
smrt-affiliates	Deprecated	Compatibility shim over the smrt-sales commissions core.
smrt-subscriptions	Preview	Plans, entitlements, usage, pricing, and spending policies.
smrt-ledgers	Stable	Double-entry accounting and journal lifecycle.
smrt-education	Preview	Tenant-aware course catalog, learner curricula, and enrollment progress with authorized private learning materials.
smrt-expenses	Preview	Reviewed expenses against a cost object, deduplicated receipts, and commitment drawdown.
smrt-ads	Stable	Ad selection, variation testing, and immutable delivery events.
smrt-analytics	Stable	Analytics properties, streams, events, and reports.
smrt-reports	Preview	Materialized aggregate definitions and refresh orchestration.
smrt-marketing	Preview	Campaign coordination, budgets, evidence, and Svelte surfaces.
smrt-inventory	Preview	SKUs, stock locations, levels, movements, and mutation service.
smrt-manufacturing	Preview	Assemblies, multi-level bills of materials, cost rollups, production runs, and production orders.
smrt-events	Stable	Nested events, series, participants, and placements.
smrt-places	Stable	Place hierarchies, geocoding, and proximity queries.
smrt-facts	Stable	Knowledge facts, provenance, confidence, and evolution.
smrt-sites	Stable	Site lifecycle and agent bindings.
smrt-properties	Stable	Digital properties and hierarchical content/ad zones.
smrt-tags	Stable	Context-scoped hierarchical tags and aliases.
smrt-secrets	Stable	Tenant envelope encryption, rotation, and audit.
smrt-features	Preview	Code-first feature flags and tenant overrides.
smrt-languages	Preview	Language strings, overrides, and translation jobs.
smrt-fields	Preview	Layered field policy store, resolution engine, and form surfaces.
smrt-preferences	Preview	Organization defaults and personal user-interface preferences: overview layouts and the shell layout.

Web, mobile, and templates

Package	Status	Purpose
smrt-ui	Stable	Domain-neutral Svelte primitives, themes, i18n, and module UI registry.
smrt-svelte	Stable	Shared Svelte 5 framework components and application shells.
smrt-web	Preview	Reactive browser collections, offline outbox, persistence, and live invalidation.
smrt-playground	Preview	Package playground discovery, runtime, and host components.
smrt-playground-host	Internal	Private SvelteKit end-to-end test host for the playground runtime.
smrt-planner	Preview	Mountable app planner: pick recipes from every package's manifest, lay out the app, and export a cookbook; ships the static planner app and its MCP widget.
smrt-mobile-contract	Preview	Manifest-to-Kotlin/Swift contract generation.
smrt-mobile	Preview	Kotlin Multiplatform offline, sync, auth, and platform seams.
smrt-android	Internal	Android Compose foundation and native adapters.
smrt-ios	Internal	SwiftUI foundation and native adapters.
smrt-template-sveltekit	Stable	Minimal SvelteKit application template.
smrt-template-site-static-json	Stable	Static JSON community-site template.
smrt-gnode	Experimental	Federation library; currently incomplete.

SDK dependencies

s-m-r-t composes infrastructure from the HappyVertical SDK, including database, AI, filesystem, logging, messaging, and provider-neutral service adapters. Use the framework packages for domain objects and generated application surfaces; use the SDK directly when implementing infrastructure adapters or lower-level services.

Development

pnpm install
pnpm build
pnpm test
pnpm typecheck
pnpm lint
pnpm workbench
pnpm check:readmes
pnpm knowledge:check --strict --format markdown

Start with a package-scoped command (pnpm --filter <package> ...) before running relevant repository-wide validation. Do not create changesets manually; release automation generates them after merge.

Local SDK development helpers:

./setup-local-dev.sh
./restore-published-deps.sh

The first command links a sibling HappyVertical SDK checkout; the second restores registry dependencies.

Documentation

• Repository architecture and agent guidance
• Core framework API and examples
• Package standards
• UI surface conventions
• AssistantDock (route-aware assistant surface)
• Documentation site

The documentation build discovers package READMEs from workspace package.json files. pnpm check:readmes prevents missing package docs, stale catalog entries, broken local README links, obsolete branding, and unsupported quick-start drift.

Related projects

• HappyVertical SDK — infrastructure packages used by s-m-r-t.
• s-m-r-t SaaS starter — reference application, demo, and template baseline.

License

MIT — see LICENSE.