ObjectStack

A metadata protocol and TypeScript toolkit for AI-native business apps. Describe your objects, permissions, workflows, APIs, UI, and AI tools once as typed, version-controlled Zod metadata — and ObjectStack derives the TypeScript types, REST API, client SDK, UI, and MCP tools from that single definition.

ObjectStack (this repo)  →  how a business app is described — the protocol + toolkit
ObjectOS                 →  where it runs, and where AI plugs in — the runtime

This repo is the framework: the protocol, kernel, SDK, and CLI you build with. To run apps and let AI operate them under your permissions, deploy on ObjectOS. · Try a live app in ~30s on StackBlitz (no install).

_{One typed definition → TypeScript types, REST API, client SDK, UI, and MCP tools.}

What is ObjectStack?

ObjectStack is an open-source metadata protocol and toolkit for describing business applications — so one typed definition powers your data model, API, UI, and AI tools. Apps run, and AI operates them under your permissions, on the ObjectOS runtime.

Instead of hiding business logic inside ad-hoc SQL queries, UI state, or JavaScript strings, ObjectStack makes the business system explicit:

• Business objects are Zod schemas with typed fields, relations, validation, and permissions.
• Business actions are generated from metadata as REST APIs, SDK calls, and MCP tools.
• Business logic is represented as analyzable metadata: flows, conditions, policies, and artifacts.
• Business runtime is a microkernel that loads plugins, drivers, services, and compiled environment artifacts.

The goal is not to be another low-code UI builder. ObjectStack is the structured definition layer for AI-native business software — agent-ready, versioned, and analyzable; permissions and audit are enforced at runtime by ObjectOS.

ObjectStack is built around three protocol layers:

• ObjectQL (Data Layer) — Objects, fields, queries, relations, validation, and data access.
• ObjectOS (Control Layer) — Runtime, permissions, automation, plugins, environments, and artifact loading.
• ObjectUI (View Layer) — Apps, views, dashboards, actions, and presentation metadata.

All core definitions start with Zod schemas (1,600+ exported schemas across 200 schema files). TypeScript types, JSON Schemas, REST routes, UI metadata, and agent tools are derived from the same source of truth.

See ARCHITECTURE.md for the full microkernel and layer architecture documentation, and content/docs/concepts/north-star.mdx for the product north star (metadata protocols · environment-aware runtime · compiled app artifacts).

Author your app — in code or in Studio

Everything is typed metadata. Define a business object once — fields, a color-coded picklist, validation — all declarative:

import { ObjectSchema, Field } from '@objectstack/spec/data';

export const Task = ObjectSchema.create({
  name: 'todo_task',
  label: 'Task',
  fields: {
    subject: Field.text({ label: 'Subject', required: true, searchable: true }),
    status: Field.select({
      label: 'Status',
      required: true,
      options: [
        { label: 'In Progress', value: 'in_progress', color: '#3B82F6' },
        { label: 'Completed', value: 'completed', color: '#10B981' },
      ],
    }),
    due_date: Field.date({ label: 'Due Date' }),
  },
});

From that single schema, ObjectStack derives the database table, an auto-generated REST API and typed client SDK, UI views (list, board, calendar, Gantt…), and MCP tools for agents — all from one definition.

Prefer clicking? Author the same metadata visually in Studio — objects, relations, validation, and flows — and it compiles to the exact same artifacts:

_{Model objects as typed metadata  ·  Automate with visual flows — both produce the same analyzable metadata.}

Want to see it running? Deploy on ObjectOS for the live Console — dashboards, boards, calendars, records, and AI working your data under your permissions.

Key Features

• AI-native, not retrofitted — Objects, permissions, flows, APIs, and UI are declarative typed metadata, small enough for an agent to load end-to-end. That metadata generates an automatic tool surface — REST APIs, client SDKs, UI views, and an MCP server — so agents inspect and act through the same contracts you defined.
• Protocol-first runtime — Every definition starts as a Zod schema (z.infer<> types), compiles into versioned, self-describing JSON artifacts, and runs on a microkernel plugin system (DI container, EventBus, init → start → destroy lifecycle).
• Data & framework reach — In-memory, PostgreSQL, MySQL, SQLite, and MongoDB drivers; 7 framework adapters (Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit); a client SDK with React hooks (useQuery / useMutation / usePagination).
• Governance & built-ins — better-auth, RBAC / RLS / FLS, a DAG-based automation engine, an MCP server that exposes the app to your own AI (BYO-AI), the ObjectUI Console, and a full CLI (os init / dev / compile / validate / …).

Why AI-native?

Most internal-tool and low-code platforms were designed for humans clicking screens. AI support is usually added later as a chat box that can call a few predefined queries. ObjectStack starts from a different assumption: AI agents need a structured, bounded, and auditable business backend before they can safely perform real work — and the entire business system has to be small enough to fit in an agent's context window.

A typical enterprise application is tens of thousands of lines of CRUD, forms, queries, permissions, and API glue spread across dozens of files. ObjectStack collapses the same surface into a few hundred lines of typed metadata — roughly two orders of magnitude less code for a developer (or an AI agent) to read, write, and maintain.

The point isn't lines of code. The point is fit in an agent's context window. When the entire business system is small, typed, and declarative, an AI agent can load it end-to-end, reason about every dependency, and safely refactor across data, API, UI, and permissions in a single change. That turns AI from an autocomplete tool into a real co-maintainer of production business software.

Dimension	Retool / Appsmith-style tools	ObjectStack
Business model	Implicit in pages, queries, and scripts	Explicit Zod ObjectSchema metadata
Code footprint	Thousands of lines of queries, JS, and UI state per app	~100× less — declarative metadata replaces CRUD, forms, validation, and API glue
Business logic	JavaScript snippets and query glue	Flows, policies, conditions, and typed metadata
External contract	App-specific UI state	Self-describing JSON Environment Artifact
Agent tools	Manually defined one by one	Generated from metadata and permissions
Agent reasoning	Calls predefined queries	Reads the full schema, composes safe actions, respects boundaries
AI maintainability	Agents must crawl sprawling app code	Whole app fits in an agent's context window
Governance	App-level conventions	Auth, RBAC, RLS, FLS, audit, and versioned artifacts

Described in ObjectStack and deployed on ObjectOS, this is the substrate for AI-native business apps — CRM, support, operations, and workflow agents acting on real business data without bypassing permissions or audit.

Quick Start

For Application Developers

# Create a new project
npx create-objectstack my-app
cd my-app

# Start dev server (REST API + console UI)
pnpm dev
# → API:    http://localhost:3000/api/v1/
# → Console: http://localhost:3000/_console/

Alternatively, with the CLI installed: os init my-app && cd my-app && os dev.

For Framework Contributors

# 1. Clone and install
git clone https://github.com/objectstack-ai/framework.git
cd framework
pnpm install

# 2. Build all packages
pnpm build

# 3. Run tests
pnpm test

# 4. Start Documentation site
pnpm docs:dev
# → http://localhost:3000/docs

Monorepo Scripts

Script	Description
pnpm build	Build all packages (excludes docs)
pnpm dev	Run the showcase kitchen-sink example (@objectstack/example-showcase) — REST + Studio; exercises every metadata type, view, automation, AI & security chain
pnpm dev:showcase	Same as pnpm dev (explicit alias)
pnpm dev:crm	Run the minimal CRM example (@objectstack/example-crm)
pnpm dev:todo	Run the Todo example (@objectstack/example-todo)
pnpm objectui:refresh	Pull the sibling ../objectui build into packages/console/
pnpm test	Run all tests (Turborepo)
pnpm setup	Install dependencies and build the spec package
pnpm docs:dev	Start the documentation site locally
pnpm docs:build	Build documentation for production

CLI Commands

The CLI binary ships as both os and objectstack.

os init [name]    # Scaffold a new project
os create         # Interactive project / object scaffolder
os dev            # Start dev server with hot-reload (REST + console)
os start          # Start the production server
os serve          # Serve a compiled artifact
os compile        # Build a deployable JSON Environment Artifact
os validate       # Validate metadata against the protocol
os lint           # Lint metadata for best-practice violations
os info           # Display project metadata summary
os generate       # Scaffold objects, views, flows, agents, migrations
os doctor         # Check environment health
os explain        # Explain protocol concepts on the command line

Cloud, package registry, and environment management subcommands (os package publish, os package install, os login, os whoami, os environments, os cloud …) are available when targeting an ObjectStack Cloud control plane.

Use the generated API

Every object ships a REST API automatically — no controllers to write:

# CRUD endpoints for the `todo_task` object you defined above
curl http://localhost:3000/api/v1/todo_task

For the browser, the typed client SDK and React hooks (useQuery / useMutation / usePagination) live in @objectstack/client-react. Need a new capability? Write a plugin, driver, or service against the same kernel APIs — every built-in is one (see below).

Package Directory

72 published packages across core, engine, drivers, client, plugins, services, adapters, tools, and examples — click to expand.

Core

Package	Description
@objectstack/spec	Protocol definitions — Zod schemas, TypeScript types, JSON Schemas, constants
@objectstack/core	Microkernel runtime — Plugin system, DI container, EventBus, Logger
@objectstack/types	Shared TypeScript type utilities
@objectstack/formula	Canonical expression engine — CEL (cel-js) + ObjectStack stdlib for formula fields, predicates, conditions, dynamic defaults
@objectstack/platform-objects	Built-in platform object schemas — identity, security, audit, notification, package, and environment

Engine

Package	Description
@objectstack/objectql	ObjectQL query engine and schema registry
@objectstack/runtime	Runtime bootstrap — DriverPlugin, AppPlugin
@objectstack/metadata	Metadata loading and persistence
@objectstack/rest	Auto-generated REST API layer

Drivers

Package	Description
@objectstack/driver-memory	In-memory driver (development and testing)
@objectstack/driver-sql	SQL driver — PostgreSQL, MySQL, SQLite (production)
@objectstack/driver-mongodb	MongoDB driver (native document database)

Turso / libSQL driver (@objectstack/driver-turso) and the libSQL-backed vector knowledge plugin (@objectstack/knowledge-turso) live in the ObjectStack Cloud monorepo as of this release.

Client

Package	Description
@objectstack/client	Client SDK — CRUD, batch API, error handling
@objectstack/client-react	React hooks — useQuery, useMutation, usePagination

Plugins

Package	Description
@objectstack/plugin-hono-server	Hono-based HTTP server plugin
@objectstack/mcp	Model Context Protocol server — exposes ObjectStack to AI agents
@objectstack/plugin-auth	Authentication plugin (better-auth)
@objectstack/plugin-security	RBAC, Row-Level Security, Field-Level Security
@objectstack/plugin-sharing	Record-level sharing — sys_record_share + enforcement middleware
@objectstack/plugin-approvals	Approval as a flow node — approver resolution, record lock & status mirror over sys_approval_request + sys_approval_action
@objectstack/plugin-audit	Audit logging plugin
@objectstack/plugin-email	Pluggable outbound email transport
@objectstack/plugin-webhooks	Outbound webhook delivery — fan-out data.record.* events
@objectstack/plugin-reports	Saved reports + scheduled email digests
@objectstack/plugin-dev	Developer mode — in-memory stubs for all services
@objectstack/plugin-msw	Mock Service Worker plugin for browser testing

Services

Package	Description
@objectstack/service-analytics	Analytics — aggregations, time series, funnels, dashboards
@objectstack/service-automation	Automation engine — flows, triggers, and workflow state machines
@objectstack/service-cache	Cache — in-memory, Redis, multi-tier
@objectstack/service-feed	Activity feed / chatter
@objectstack/service-i18n	Internationalization service
@objectstack/service-job	Cron & interval job scheduler
@objectstack/service-package	Package registry — publish, version, retrieve metadata packages
@objectstack/service-queue	Background job queue (in-memory, BullMQ)
@objectstack/service-realtime	Real-time events and subscriptions
@objectstack/service-settings	Settings — manifest registry + K/V resolver (Env > Tenant > User)
@objectstack/service-storage	File storage (local, S3, R2, GCS)

Framework Adapters

Package	Description
@objectstack/express	Express adapter
@objectstack/fastify	Fastify adapter
@objectstack/hono	Hono adapter (Node.js, Bun, Deno, Cloudflare Workers)
@objectstack/nestjs	NestJS module integration
@objectstack/nextjs	Next.js App Router adapter
@objectstack/nuxt	Nuxt adapter (h3-based)
@objectstack/sveltekit	SvelteKit adapter

Tools & Apps

Package / App	Description
@objectstack/cli	CLI binary (os / objectstack) — init, dev, start, serve, compile, publish, validate, generate, lint, doctor
create-objectstack	Project scaffolder (npx create-objectstack)
objectstack-vscode	VS Code extension — autocomplete, validation, diagnostics
@object-ui/console	Fork-ready runtime console SPA (lives in objectstack-ai/objectui, served via @object-ui/console on npm)
@objectstack/account	Account & identity portal — sign in, organizations, connected apps
@objectstack/docs	Documentation site (Fumadocs + Next.js)

Examples

Example	Description	Level
@objectstack/example-todo	Task management app — objects, views, dashboards, flows	Beginner
@objectstack/example-crm	Minimal CRM smoke-test workspace — validates the metadata loading pipeline	Intermediate
HotCRM	Full-featured enterprise CRM reference app (separate repo)	Advanced

Architecture

ObjectStack uses a microkernel architecture where the kernel provides only the essential infrastructure (DI, EventBus, lifecycle), and all capabilities are delivered as plugins. The three protocol layers sit above the kernel:

See ARCHITECTURE.md for the complete design documentation including the plugin lifecycle state machine, dependency graph, and design decisions.

Roadmap

See ROADMAP.md for the current documentation and architecture cleanup priorities.

Contributing

We welcome contributions. Please read CONTRIBUTING.md for the development workflow, coding standards, testing requirements, and documentation guidelines.

Key standards:

• Zod-first — all schemas start with Zod; TypeScript types are derived via z.infer<>
• camelCase for configuration keys (e.g., maxLength, defaultValue)
• snake_case for machine names / data values (e.g., project_task, first_name)

Documentation

Full documentation: https://docs.objectstack.ai

Run locally: pnpm docs:dev

Community

• ⭐ Star this repo if ObjectStack is useful — it helps others find it.
• 🐛 Questions, bugs, or feature requests → open an issue.
• 🤝 Want to contribute? See CONTRIBUTING.md.

License

Apache-2.0. Enterprise editions, official cloud services, and marketplace commercial terms live outside this repository.