Skip to content

examples

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

examples

README.md

ObjectStack Examples Catalog

Comprehensive examples demonstrating all ObjectStack protocols and features

Welcome to the ObjectStack examples catalog! This directory contains carefully crafted examples organized by complexity and use case to help you get started quickly and learn the platform effectively.

📚 Quick Navigation

By Learning Path

Level Examples Description
🟢 Beginner Todo, Basic Start here - simple, focused examples
🟡 Intermediate CRM, Plugin Advanced CRM Real-world applications
🔴 Advanced MSW React CRUD, Host Server Complex integrations

By Protocol Category

Protocol Examples Status
Data (ObjectQL) Basic Data, CRM Objects, Todo ✅ Complete
UI (ObjectUI) Basic UI, CRM UI, MSW React ✅ Complete
System (ObjectOS) Basic System, Host Server, Middleware ✅ Complete
AI AI Sales, AI Support, AI Analyst, AI Codegen, Basic AI/RAG ✅ Complete
Automation Basic Automation, CRM Workflows ✅ Complete
Auth & Permissions Basic Auth, CRM Permissions ✅ Complete
API REST Server, API Discovery, Host Server ✅ Complete
Integration Plugin BI, Advanced CRM Plugin 🟡 Partial
Hub & Marketplace Coming soon 🔴 Missing

🎯 Example Descriptions

Todo App

Path: examples/todo/
Level: 🟢 Beginner
Protocols: Data, UI, System

The simplest complete example. Perfect for your first ObjectStack application.

What you'll learn:

  • Basic object definitions
  • Simple CRUD operations
  • Basic UI configuration
  • Package structure with objectstack.config.ts

Quick Start:

cd examples/todo
pnpm install
pnpm typecheck

Basic Protocol Examples

Path: examples/basic/
Level: 🟢 Beginner
Protocols: All (70+ protocols)

Comprehensive standalone examples for every core protocol. Each file is self-contained and runnable.

Examples included:

Quick Start:

# Run any example directly
npx tsx examples/basic/stack-definition-example.ts

# Or type check all examples
cd examples/basic
pnpm typecheck

CRM Example

Path: examples/crm/
Level: 🟡 Intermediate
Protocols: Data, UI, Automation, Auth

Full-featured CRM demonstrating enterprise-grade patterns and all major field types.

What's included:

  • 6 interconnected objects (Account, Contact, Opportunity, Lead, Case, Task)
  • All 28 field types demonstrated
  • Multiple view types (Grid, Kanban, Calendar, Gantt)
  • Validation rules and workflows
  • Dashboards and reports
  • Actions and automation

Object Highlights:

  • Account: Formulas, validation, workflows, autonumber
  • Contact: Master-detail relationships, avatars
  • Opportunity: State machines, complex workflows, history tracking
  • Lead: Conversion processes, status management
  • Case: SLA tracking, escalation automation
  • Task: Polymorphic relationships, time tracking

Quick Start:

cd examples/crm
pnpm install
pnpm build

MSW React CRUD

Path: examples/msw-react-crud/
Level: 🔴 Advanced
Protocols: Data, UI, API, Client

Frontend-first development - Run ObjectStack entirely in the browser with Service Workers.

What you'll learn:

  • Browser-based ObjectStack kernel
  • MSW (Mock Service Worker) integration
  • React client with @objectstack/client-react
  • In-memory data persistence
  • Full CRUD without backend

Architecture:

React App → Service Worker → ObjectStack Kernel → In-Memory Driver

Quick Start:

cd examples/msw-react-crud
pnpm install
pnpm dev
# Open http://localhost:5173

Host Server

Path: examples/host/
Level: 🔴 Advanced
Protocols: System, API, Data

Complete server implementation showing how to build a metadata-driven backend.

Features:

  • Dynamic schema loading from plugins
  • Auto-generated REST APIs
  • Unified metadata API
  • Plugin orchestration
  • Production-ready patterns

Quick Start:

cd examples/host
pnpm install
pnpm dev
# API available at http://localhost:3000

AI Examples

AI Sales Assistant

Path: examples/ai-sales/
Protocols: AI (Agent, RAG, NLQ)

Intelligent sales automation with lead qualification, email personalization, and opportunity insights.

AI Support Assistant

Path: examples/ai-support/
Protocols: AI (Agent, RAG, Model Registry)

RAG-powered customer support with vector search knowledge base.

AI Data Analyst

Path: examples/ai-analyst/
Protocols: AI (NLQ, Agent)

Natural language query system transforming questions into ObjectQL queries.

AI Code Generator

Path: examples/ai-codegen/
Protocols: AI (Agent, Orchestration)

Generate complete ObjectStack applications from natural language descriptions.

Plugin Examples

Plugin Advanced CRM

Path: examples/plugin-advanced-crm/
Protocols: System (Plugin, Capabilities, Services)

Demonstrates plugin architecture with capability manifests, protocol conformance, and service interfaces.

Plugin BI

Path: examples/plugin-bi/
Protocols: UI (Dashboard, Report, Chart), Integration

Business intelligence plugin with advanced analytics and data visualization.

Standalone Examples

REST Server Example

Path: examples/rest-server-example.ts
Protocols: API (REST, Endpoint, Router)

Single-file REST API server implementation showing minimal server setup.

Middleware Example

Path: examples/middleware-example.ts
Protocols: System (Plugin, Lifecycle), API (HTTP)

Demonstrates plugin middleware patterns and HTTP interceptors.

🗺️ Protocol Coverage Map

Data Protocol (ObjectQL)

Protocol Example Location
Object Definition ✅ Complete CRM Objects, Todo
Field Types (28 types) ✅ Complete CRM Account
Validation Rules ✅ Complete CRM Examples, Basic
Relationships ✅ Complete CRM Contact
Formulas ✅ Complete CRM Account
Hooks ✅ Complete CRM Hooks
Query & Filters ✅ Complete Basic
External Lookup 🟡 Partial Plugin BI
Document Storage 🔴 Missing Planned

UI Protocol (ObjectUI)

Protocol Example Location
List Views ✅ Complete CRM - Grid, Kanban, Calendar, Gantt
Form Views ✅ Complete CRM - Simple, Tabbed, Wizard
Actions ✅ Complete CRM Actions
Dashboards ✅ Complete CRM Dashboards
Reports ✅ Complete CRM Reports
Charts ✅ Complete CRM, Plugin BI
Widgets ✅ Complete CRM Dashboards
Themes 🟡 Partial Basic
Pages 🟡 Partial Basic
Components 🔴 Missing Planned

System Protocol (ObjectOS)

Protocol Example Location
Manifest ✅ Complete All examples with objectstack.config.ts
Plugin System ✅ Complete Plugin Advanced CRM, Host
Capabilities ✅ Complete Basic Capabilities
Logging ✅ Complete Basic Logger
Events ✅ Complete Middleware
Service Registry ✅ Complete Plugin Advanced CRM
Datasources 🟡 Partial Basic
Job Scheduling 🔴 Missing Planned
Metrics 🔴 Missing Planned
Tracing 🔴 Missing Planned
Object Storage 🔴 Missing Planned
Search Engine 🔴 Missing Planned
Message Queue 🔴 Missing Planned
Cache 🔴 Missing Planned
Encryption 🔴 Missing Planned
Compliance 🔴 Missing Planned
Audit 🔴 Missing Planned

AI Protocol

Protocol Example Location
Agent ✅ Complete AI Sales, AI Support
RAG Pipeline ✅ Complete AI Support, Basic RAG
Model Registry ✅ Complete AI Support
NLQ (Natural Language Query) ✅ Complete AI Analyst
Conversation ✅ Complete AI Sales
Orchestration ✅ Complete AI Codegen
Cost Tracking 🟡 Partial AI Examples
Predictive Analytics 🔴 Missing Planned

Automation Protocol

Protocol Example Location
Workflow Rules ✅ Complete CRM, Basic
Flow (Visual) ✅ Complete Basic Automation
Approval Processes ✅ Complete Basic Automation
ETL Pipelines ✅ Complete Basic Automation
Webhooks 🟡 Partial Basic
Triggers ✅ Complete CRM
Sync 🔴 Missing Planned

Auth & Permissions

Protocol Example Location
Identity & Sessions ✅ Complete Basic Auth
Roles & RBAC ✅ Complete Basic Auth
Permissions ✅ Complete Basic Auth, CRM
Row-Level Security (RLS) ✅ Complete Basic Auth
Sharing Rules ✅ Complete Basic Auth
Territory Management ✅ Complete Basic Auth
OAuth/OIDC Config 🟡 Partial Plugin Advanced CRM
SCIM 🔴 Missing Planned
Organizations 🔴 Missing Planned

API Protocol

Protocol Example Location
REST Server ✅ Complete REST Server, Host
API Discovery ✅ Complete Basic Discovery
GraphQL 🟡 Partial Basic
OData 🔴 Missing Planned
WebSocket/Realtime 🔴 Missing Planned
Batch Operations 🔴 Missing Planned
HTTP Cache 🔴 Missing Planned
Error Handling 🟡 Partial REST Server

Integration Protocol

Protocol Example Location
Database Connectors 🟡 Partial Plugin Advanced CRM
File Storage Connectors 🔴 Missing Planned
Message Queue Connectors 🔴 Missing Planned
SaaS Connectors 🔴 Missing Planned

Hub & Marketplace

Protocol Example Location
Plugin Registry 🟡 Partial Plugin Examples
Marketplace 🔴 Missing Planned
Licensing 🔴 Missing Planned
Composer 🔴 Missing Planned
Spaces 🔴 Missing Planned
Multi-tenancy 🔴 Missing Planned

🚀 Getting Started

Prerequisites

# Ensure you have Node.js 18+ and pnpm installed
node --version  # >= 18.0.0
pnpm --version  # >= 8.0.0

Quick Start

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

# 2. Build the spec package
pnpm --filter @objectstack/spec build

# 3. Run any example
npx tsx examples/basic/stack-definition-example.ts

# 4. Or explore a full app
cd examples/crm
pnpm build

Learning Path

Path 1: Quick Start (1-2 hours)

  1. Read Todo Example - Understand basic structure
  2. Run Basic Stack Definition - See patterns
  3. Explore CRM Example - Learn advanced features

Path 2: Deep Dive (1-2 days)

  1. Complete Path 1
  2. Study all Basic Examples - Master each protocol
  3. Build Plugin Advanced CRM - Understand plugins
  4. Try MSW React CRUD - Frontend integration

Path 3: AI & Advanced (2-3 days)

  1. Complete Path 1 & 2
  2. Study AI Support - RAG patterns
  3. Try AI Analyst - NLQ patterns
  4. Explore AI Codegen - AI orchestration
  5. Build Host Server - Production backend

📝 Example Standards

All examples in this directory follow these standards:

Code Quality

  • ✅ Type-safe: All examples use TypeScript and pass typecheck
  • ✅ Zod-first: Schemas defined with Zod, types inferred
  • ✅ Naming conventions: camelCase for config, snake_case for data
  • ✅ Documented: Comprehensive inline comments
  • ✅ Best practices: Follow ObjectStack conventions

File Structure

example-name/
├── README.md              # Comprehensive documentation
├── package.json           # Package definition
├── tsconfig.json          # TypeScript config
├── objectstack.config.ts  # Main configuration
└── src/                   # Source code
    ├── domains/           # Object definitions
    ├── ui/                # UI components
    └── ...

Documentation Requirements

Each example MUST have:

  • Clear purpose statement
  • Prerequisites and dependencies
  • Quick start instructions
  • Protocol coverage explanation
  • Key concepts highlighted
  • Related examples linked

🤝 Contributing Examples

Want to add an example? Great! Please ensure:

  1. Follow the standards above
  2. Fill a gap in protocol coverage
  3. Add documentation (README.md)
  4. Test thoroughly (must compile and run)
  5. Submit PR with clear description

See CONTRIBUTING.md for details.

📚 Additional Resources

📄 License

All examples are licensed under Apache 2.0. See LICENSE for details.

Last Updated: 2026-01-31
Protocol Version: 0.6.1
Total Examples: 15
Protocol Coverage: 60/108 (56%)