ObjectStack Protocol

The "Constitution" of the Post-SaaS Operating System.

This repository contains the core specifications, schemas, and protocols that power the ObjectStack ecosystem. It defines how data, UI, and system configurations are expressed as code.

🎯 What is ObjectStack?

ObjectStack is a metadata-driven platform built on three foundational protocols:

• ObjectQL (Data Layer) — Define data structure and queries
• ObjectOS (Control Layer) — Runtime, permissions, and workflows
• ObjectUI (View Layer) — Presentation and user interaction

Learn more:

• Three-Layer Stack — How ObjectQL, ObjectOS, and ObjectUI work together
• Architecture Guide — Complete microkernel architecture documentation

📚 Documentation

📖 Read the Full Documentation or run locally with pnpm docs:dev

Quick Links

• Getting Started:

  • Introduction — Core concepts and architecture
  • CLI Guide — init, dev, serve, studio, compile, validate
  • Quick Reference — Fast protocol lookup

• Protocol References:

  • Protocol Reference — All protocol specifications (175 Zod schemas)
  • ObjectQL — Data layer documentation
  • ObjectUI — UI layer documentation
  • ObjectOS — System layer documentation

• Development:

  • Developer Guide — Tutorials and best practices
  • Package Reference — All 25 packages
  • Contributing Guide — How to contribute

🚀 Quick Start

For Application Developers

# Create a new project
npx @objectstack/cli init my-app
cd my-app

# Start development server
os dev

# Start with Console UI (Object Explorer, Schema Inspector)
os studio
# → API:     http://localhost:3000/api/v1/
# → Console: http://localhost:3000/_studio/

For Protocol Developers

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

# 2. Build all packages
pnpm build

# 3. Check environment health
pnpm doctor

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

# 5. Launch Console UI + dev server
pnpm studio

Monorepo Scripts

Script	Description
pnpm build	Build all packages (excludes docs)
pnpm dev	Start app-host example dev server
pnpm studio	Launch Console UI with dev server
pnpm dev:console	Start Console standalone (MSW mode)
pnpm test	Run spec tests
pnpm doctor	Check environment health
pnpm docs:dev	Start documentation site
pnpm docs:build	Build documentation for production

CLI Commands

os init [name]       # Scaffold a new project
os dev               # Start dev server (hot-reload)
os dev --ui          # Dev server + Console UI
os studio            # Alias for dev --ui (one command)
os serve             # Start production server
os compile           # Build deployable JSON artifact
os validate          # Check configuration against protocol
os info              # Display metadata summary
os generate          # Scaffold objects, views, flows
os doctor            # Check environment health

📦 Monorepo Structure

Core Packages

Package	Description	Status
@objectstack/spec	Protocol definitions (Zod schemas, Types, JSON Schemas)	🟢 Active
@objectstack/core	Microkernel runtime (Plugin system, DI, Event Bus, Logger)	🟢 Active
@objectstack/types	Shared runtime type definitions	🟢 Active

Engine Packages

Package	Description	Status
@objectstack/objectql	ObjectQL query engine and schema registry	🟢 Active
@objectstack/runtime	Runtime utilities, DriverPlugin, AppPlugin	🟢 Active
@objectstack/metadata	Metadata loading and persistence	🟢 Active
@objectstack/rest	REST API Server — auto-generated endpoints from protocol	🟢 Active

Client Packages

Package	Description	Status
@objectstack/client	Official Client SDK (CRUD, Batch API, Error handling)	🟢 Active
@objectstack/client-react	React hooks (useQuery, useMutation, usePagination)	🟢 Active

Plugin Packages

Package	Description	Status
@objectstack/driver-memory	In-memory driver (reference implementation, zero deps)	🟢 Active
@objectstack/plugin-hono-server	HTTP server plugin (Hono-based, auto-discovery)	🟢 Active
@objectstack/plugin-msw	Mock Service Worker plugin for browser testing	🟢 Active
@objectstack/plugin-auth	Authentication & identity plugin (better-auth based)	🟡 In Development
@objectstack/plugin-security	RBAC, Row-Level Security, and Field-Level Security	🟢 Active
@objectstack/plugin-dev	Dev mode — auto-enables all services with in-memory stubs	🟢 Active

Framework Adapters

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

Tools & Apps

Package	Description	Status
@objectstack/cli	CLI: init, dev, serve, studio, compile, validate, generate	🟢 Active
create-objectstack	Project scaffolder (npx create-objectstack)	🟢 Active
objectstack-vscode	VSCode extension — autocomplete, validation, diagnostics	🟢 Active
@objectstack/studio	Studio UI (Object Explorer, Schema Inspector)	🟢 Active
@objectstack/docs	Documentation site (Fumadocs + Next.js)	🟢 Active

Examples

Example	Description	Level
@example/app-todo	Task management app — objects, views, dashboards, flows	🟢 Beginner
@example/app-crm	Enterprise CRM — accounts, contacts, opportunities, leads	🟡 Intermediate
@example/app-host	Server host — multi-app orchestration with plugins	🔴 Advanced
@example/plugin-bi	BI plugin — analytics objects and reports	🟡 Intermediate

🗺️ Roadmap

See ROADMAP.md for the next-phase optimization and improvement plan (Phases 5–11), covering:

• Spec test coverage completion (100% schema coverage)
• Runtime package hardening (resolve all TODOs)
• Framework adapter implementations (Hono, Next.js, NestJS)
• Deprecation cleanup & v3.0 preparation
• Developer experience & tooling improvements
• Performance optimization & security hardening

Studio-specific roadmap: apps/studio/ROADMAP.md

Visual design UX optimization plan: docs/design/visual-design-ux-optimization.md

🤝 Contributing

We welcome contributions! Please read our Contributing Guide for:

• Development workflow and setup
• Coding standards (Zod-first, camelCase config, snake_case data)
• Testing requirements
• Documentation guidelines

Key Standards:

• All schemas defined using Zod with runtime validation
• Configuration keys: camelCase (e.g., maxLength)
• Machine names: snake_case (e.g., project_task)
• Comprehensive JSDoc comments

📄 License

Apache 2.0 © ObjectStack