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

Architecture Documentation

• Architecture Guide - Complete microkernel architecture overview
• Quick Reference - Fast lookup for developers
• Package Dependencies - Dependency graph and build order

Quick Links

• Getting Started:

  • Introduction - Core concepts and architecture
  • 📚 Examples Catalog - Comprehensive examples for all protocols
  • Quick Start: Todo App - Simplest complete example
  • Quick Start: Basic Examples - Protocol-by-protocol examples

• Protocol References:

  • Protocol Reference - All 109 protocol specifications
  • ObjectQL - Data layer documentation
  • ObjectUI - UI layer documentation
  • ObjectOS - System layer documentation

• Examples by Use Case:

  • CRM Example - Full-featured enterprise CRM
  • AI Examples - AI Sales, Support, Analyst, Codegen
  • Integration Examples - External system connectors
  • System Examples - Production-grade patterns
  • API Examples - GraphQL, OData, WebSocket
  • Hub Examples - Marketplace & Plugins

• Development:

  • Architecture Guide - Complete architecture overview
  • MicroKernel Architecture - Plugin architecture guide
  • Plugin Ecosystem - Plugin interoperability
  • Writing Plugins - Plugin development guide
  • Contributing Guide - How to contribute

🚀 Quick Start

For Application Developers (Using the Client SDK)

If you want to build applications using ObjectStack:

# Install the client SDK
pnpm add @objectstack/client

# For React applications
pnpm add @objectstack/client-react

import { ObjectStackClient } from '@objectstack/client';

// Connect to your ObjectStack server
const client = new ObjectStackClient({
  baseUrl: 'http://localhost:3004'
});

await client.connect();

// Query data
const tasks = await client.data.find('todo_task', {
  select: ['subject', 'priority'],
  filters: ['status', '=', 'active'],
  sort: ['-priority'],
  top: 10
});

// Create data
await client.data.create('todo_task', {
  subject: 'New Task',
  priority: 1
});

📖 View Client SDK Documentation - Complete SDK reference with React hooks

For Protocol Developers (Contributing to ObjectStack)

If you want to contribute to the ObjectStack protocol or build plugins:

# 1. Install dependencies
pnpm install

# 2. Build the Protocol (Generates Schemas & Docs)
pnpm --filter @objectstack/spec build

# 3. Check environment health
pnpm doctor

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

For Plugin/Package Development

See DEVELOPMENT.md for comprehensive development guide including:

• Development workflow and tooling
• CLI commands reference
• Debugging configurations
• Testing strategies
• Common tasks and troubleshooting

📦 Monorepo Structure

Core Packages

Package	Description	Key Features	Status
@objectstack/spec	Protocol definitions (Zod schemas, Types, JSON Schemas) - The "Constitution"	Runtime validation, Type inference, JSON Schema generation	🟢 Active
@objectstack/core	Microkernel runtime (Plugin system, DI, Event Bus, Logger)	Plugin lifecycle, Service registry, High-performance logging	🟢 Active
@objectstack/types	Shared runtime type definitions	IKernel, RuntimePlugin, RuntimeContext interfaces	🟢 Active

Engine Packages

Package	Description	Key Features	Status
@objectstack/objectql	ObjectQL query engine and schema registry	Cross-datasource queries, Driver routing, Schema registry	🟢 Active
@objectstack/runtime	Runtime utilities and plugin helpers	Standard library, DriverPlugin, AppPlugin	🟢 Active
@objectstack/metadata	Metadata loading and persistence	Multi-format support, File watching, Validation	🟢 Active

Client Packages

Package	Description	Key Features	Status
@objectstack/client	Official Client SDK for ObjectStack Protocol	CRUD operations, Batch API, View storage, Error handling	🟢 Active
@objectstack/client-react	React hooks for ObjectStack	useQuery, useMutation, usePagination, useInfiniteQuery	🟢 Active

Plugin Packages

Package	Description	Key Features	Status
@objectstack/driver-memory	In-memory driver (reference implementation)	Zero dependencies, Perfect for testing, Fast in-memory storage	🟢 Active
@objectstack/plugin-hono-server	HTTP server plugin (Hono-based)	Universal runtime, Auto-discovery, API Registry integration	🟢 Active
@objectstack/plugin-msw	Mock Service Worker plugin for testing	Automatic API mocking, Browser & Node support	🟢 Active

Tools

Package	Description	Key Features	Status
@objectstack/cli	Command-line interface and development tools	serve, dev, compile, doctor, create, test:run	🟢 Active
@objectstack/docs	Documentation site (Fumadocs + Next.js)	Interactive docs, API reference, Examples	🟢 Active

Package Quick Links

For Application Developers:

• Start here: @objectstack/client - Official SDK
• React apps: @objectstack/client-react - React hooks
• Development: @objectstack/cli - CLI tools

For Protocol Developers:

• Protocols: @objectstack/spec - Schema definitions
• Runtime: @objectstack/core - Microkernel
• Data layer: @objectstack/objectql - Query engine

For Plugin Developers:

• Runtime: @objectstack/runtime - Plugin patterns
• Types: @objectstack/types - Shared interfaces
• Examples:
  • @objectstack/driver-memory - Driver reference
  • @objectstack/plugin-hono-server - Server plugin

Examples

Package	Description	Status
examples/crm	Full-featured CRM example	🟢 Complete
examples/todo	Simple todo app example	🟢 Active

📖 View Full Architecture Guide - Comprehensive architecture documentation

🤝 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
• 80%+ test coverage

📄 License

Apache 2.0 © ObjectStack