Framework

One application definition supplies every interface.

smrt-core supplies the model, collection, registry, persistence, and generation foundation. A model describes the fields, relationships, operations, and interface choices for one kind of record.

The framework uses that shared description for storage, collections, forms, APIs, commands, tools, and permission names. Application modules use the same foundation. They do not add parallel definitions that can drift.

Model to surfaces

Describe the record once.

This Article model selects four REST actions and one MCP action. It disables CLI access. Field metadata also marks one required value, one read-only value, and one sensitive value.

src/lib/objects/Article.ts

typescript

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

@smrt({
  api: {
    include: ['list', 'get', 'create', 'update']
  },
  mcp: { include: ['publish'] },
  cli: false,
  ui: {
    label: 'Articles',
    description: 'Stories your team publishes.'
  }
})
export class Article extends SmrtObject {
  title = '';
  body = '';
  featured = false;

  @field({ required: true })
  author = '';

  @field({
    readonly: true,
    description: 'Server-set; writes cannot touch it.'
  })
  viewCount = 0;

  @field({
    sensitive: true,
    exported: false,
    description: 'Editorial notes for the team.',
    ui: { group: 'Editorial', order: 10 }
  })
  authorNotes = '';

  async publish() {
    return true;
  }
}

Persons and software agents can reach the same permitted application operations. This is Software as Agentic Domain Logic (SAADL). The shared model keeps the human and agent interfaces on one contract. It does not give an agent authority.

Concept families

Follow the framework from meaning to operation.

These pages explain concepts and guarantees. The Reference section holds exhaustive contracts and API details.

01
Models and collections

Write one TypeScript class for a record such as an Article or Invoice. The framework uses that class to understand its data and operations.
02
Persistence and live data

The framework prepares storage from the model. It can render server data first, give the same rows to the browser, and report later changes.
03
Tenancy and identity

A login account, a person, and an organization are different records. A membership states which account can act in which organization.
04
Permissions and security

Knowing who made a request is not enough. The application must also check the tenant, the operation, and protected fields.
05
Generated interfaces

The framework creates several ways to use the application. They share one description, so their names and field rules stay consistent.
06
Agent awareness and introspection

An application can describe its models and permitted tools. Coding tools can describe the project source. These descriptions do not give either kind of agent more authority.

Framework 01

Describe application logic with models and collections

A model describes one kind of application record. Its collection supplies the standard read and write operations for those records.

Your class

DatabaseManifestRESTMCPCLI

One object description supports the rest of the application.

smrt-core supplies the shared foundation

smrt-core supplies SmrtObject, SmrtCollection, ObjectRegistry, database integration, change observation, and the generation hooks. Framework packages and application modules build on these same primitives.

SmrtObject keeps fields, relationships, validation, and useful methods together.
SmrtCollection supplies list, get, count, create, query, and relationship loading.
ObjectRegistry holds the live classes, fields, relationships, and collection registrations.
Other packages add identity, tenancy, UI, agents, and application modules without a second model system.

The model is the application definition

The class fields describe stored values. Decorators add relationships, tenant scope, interface actions, permissions, and UI descriptions. Methods hold application operations beside the data they use.

Field names and types become stable metadata.
Relationship decorators connect models without a second relationship schema.
Interface include lists select the operations that each generated surface can expose.
Sensitive and read-protected fields stay outside generated public descriptions.

Collections keep read behavior consistent

A normal collection list returns model instances with their methods. A selected list returns smaller plain rows. Both paths use the same field mapping, interceptors, tenant rules, and query limits.

Collections reference →Relationships reference →

Framework 02

Keep server and browser data on one contract

The manifest supplies the database shape and generated data clients. Server collections and browser collections use that shared description.

Web collection

Server loadHydrationSSEIndexedDBSync

Server rows become a live browser collection without another first fetch.

The manifest drives persistence

The scanner records model fields, relationships, table strategy, indexes, and tenant scope. Database migration uses that manifest. Runtime code does not create missing application tables in response to a request.

Migrations prepare SQLite or PostgreSQL before application traffic starts.
Server collections map TypeScript field names to database columns.
Interceptors apply tenant and application rules to the normal collection path.

Hydration passes the first result to the browser

SvelteKit can load rows on the server and seed a generated browser collection with those rows. The first browser read can use the seed instead of making a duplicate request.

A shared browser client lets collections share cache entries.
Generated fetchers use the same REST route scheme as the model surface.
Manifest hashes separate client data that belongs to incompatible definitions.

Change records support live and offline work

Writes append durable records to _smrt_changes. The _events stream can signal a browser to read from its last cursor. Polling is the fallback when the signal path is not available.

The change feed stores durable order and resume cursors.
The signal path is a prompt to read the durable feed, not a second data source.
An offline outbox replays writes through the same server contract with idempotency keys.

Hydration and live-data capability →

System facilities have narrow jobs

Tables with the _smrt_ prefix support framework operations. For example, _smrt_changes stores change records, _smrt_contexts stores scoped memory, and _smrt_embeddings stores retrieval vectors. They do not replace application models.

AI and retrieval reference →Semantic search guide →

Framework 03

Separate identity, organization, and membership

Users authenticate. Profiles describe persons. Tenants define organization boundaries. Memberships connect these records for access decisions.

Membership

UserProfileTenantRolePermission

Authentication, product identity, organization, and access remain separate.

Each identity record has one job

A User is an authentication identity. A Profile is the application identity for a person or organization. A Tenant is an account or organization boundary. These records can change independently.

Identity-provider bindings attach external sign-in identities to a User.
Profile relationships describe application meaning such as client, supplier, or representative.
Tenant parent and child links describe an organization hierarchy.

Membership connects a user to a tenant

A Membership joins one User, one Tenant, and one Role. A direct membership takes precedence in its tenant. A role can opt in to authority for descendant tenants.

An inactive direct membership denies access for that tenant.
Ancestor membership authority is opt-in and uses the nearest valid ancestor.
Group roles and tenant overrides stay inside their defined tenant boundary.

Tenant context scopes data operations

Tenant context adds the tenant identifier to normal collection reads and writes for a tenant-scoped model. Missing required context fails closed. System and super-admin bypasses are explicit server operations.

Multi-tenant lifecycle guide →Security reference →

Framework 04

Resolve authority at each operation boundary

Authentication identifies a caller. Tenant scope limits the data boundary. Operation permissions decide whether that caller can perform an action.

Tenant

Parent / childMembershipRole inheritanceProfile relationship

Organization, user access, and business relationships use different links.

The manifest supplies stable operation names

The permission catalog derives names from the model and its exposed actions. A standard read maps to a name such as articles.read. A custom action maps to its own stable name.

Application guards check the catalog before hand-written actions run.
Generated routes enforce authentication, tenant scope, writable fields, and operation rules.
PostgreSQL row-level policies can apply the same resolved permission set at the data layer.

Specific limits can only narrow authority

Roles, groups, tenant rules, and membership overrides resolve in a defined order. A membership deny wins at the final step. Application agents add their own class and persona tool limits to the user permission set.

A tenant deny can remove a permission that a role or group granted.
A user-specific deny is final.
Delegation between application agents keeps the same principal and cannot add authority.

Descriptions do not grant access

An agent can know that a model, field, or operation exists without permission to read or change its data. Sensitive fields stay out of public model descriptions. The server resolves every requested operation as the active principal.

Authorization reference →Security reference →

Framework 05

Generate each interface from the same model

One model can supply storage, forms, REST routes, commands, MCP tools, WebMCP tools, and permission names. Each surface can expose a different action set.

Manifest

RESTMCPWebMCPCLIBrowser

Each interface reads the same declared model capabilities.

Generation starts with declared actions

Each model selects its REST, MCP, and CLI actions. The generator reads the merged manifest and emits only the selected surface. The shared model description prevents a route schema and a tool schema from changing independently.

REST routes and clients serve application code.
MCP tools serve connected application agents.
WebMCP tools serve agents through an active browser page.
CLI resources serve operators and scripts.
Generated web collections serve browser data and forms.

Stable descriptions prevent interface drift

Model, field, relationship, operation, and permission names come from the same manifest entries. Descriptions and JSON Schema inputs travel with the operation. A model change is therefore visible to each regenerated interface.

Fields use the same logical names across generated clients and tools.
Relationship metadata identifies linked models without page-specific inference.
Writable, sensitive, and permission-protected field rules apply before execution.

The server remains the authority boundary

Generation does not make every action public. The host selects the surface, resolves the caller, applies tenant context, and checks the operation. A browser tool uses the signed-in page session. A remote MCP gateway resolves a principal for each request.

Complete generated-interface reference →WebMCP concept →Expose an application over MCP →

Framework 06

Give agents stable application descriptions

Source manifests, the runtime ObjectRegistry, generated operations, and version-matched knowledge help agents understand an application without guessing from files or pixels.

Agent understanding

Domain manifestOptional runtime bridgeForm controlsMCP tools

Explicit registries describe the application from source through the active interface.

Source and runtime answer different questions

The source manifest describes declared objects, fields, relationships, methods, permissions, and generated interfaces. ObjectRegistry describes the model and collection classes registered in the active process.

.smrt/manifest.json is the runtime-focused source artifact.
.smrt/smrt-knowledge.json is the deterministic review and architecture artifact.
ObjectRegistry holds active constructors, collections, field metadata, relationships, and decorator configuration.
Generated REST, MCP, WebMCP, and CLI descriptions use stable names and structured inputs.

System facilities add operational context

Relevant _smrt_ facilities hold framework state with defined contracts. Change records, memory, embeddings, dispatch records, migrations, and field policies each have a narrow role. Agents must use the public framework operation for that role instead of treating the tables as an open data API.

_smrt_changes provides resumable change records.
_smrt_contexts and _smrt_embeddings support scoped memory and retrieval.
_smrt_dispatch stores durable application signals.
_smrt_migrations and _smrt_backfills record framework maintenance work.

Application agents and coding agents are different

An application agent operates the running application through a host-selected tool surface. A coding agent works on source, configuration, tests, and generated project knowledge. The two audiences use related descriptions but different authority boundaries.

Application agents act as a resolved principal and remain inside tenant, permission, and tool limits.
Coding agents use installed package instructions, workspace manifests, and development introspection.
A coding tool does not become an application data principal because it can read project metadata.
An application tool does not gain source-edit authority because it can describe a model.

Runtime development introspection has a release boundary

The current development MCP reads workspace and installed-package artifacts. A bridge to a running ObjectRegistry is available only when the installed development MCP explicitly supplies that integration. Do not infer a live connection from source introspection alone.

Development MCP and its runtime boundary →

SAADL joins meaning and governed operations

Software as Agentic Domain Logic describes an application where persons and software agents reach the same permitted application operations. The application does not maintain a separate, reduced agent definition that can drift from the human interface.

Complete SAADL terminology entry →Human-agent interaction →

Awareness stays separate from authority

A stable description lets an agent plan and explain. It does not supply credentials, tenant data, or permission. The host chooses the visible operations, and the server checks each request.

Authorization reference →Agent-assisted forms →

Continue by task

Use the section that owns the next question.

Reference Look up complete interface, permission, security, and package contracts. Guides Follow task procedures for setup, integration, migration, and testing. Interaction Understand how persons and application agents communicate and share control. UI See the controls and shell that make application state and authority visible. Application modules Find prebuilt application parts that use the same framework foundation. Tooling Use development tools and coding-agent introspection for source work.