examples

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	App Todo, Plugin BI	Start here - simple, focused examples
🟡 Intermediate	HotCRM	Real-world enterprise application (separate repo)
🟣 Reference	App Showcase	Kitchen-sink — every metadata type, view type, and chart type, plus a coverage test
🔴 Advanced	Server	Server hosting & plugin orchestration

By Protocol Category

Protocol	Examples	Status
Data (ObjectQL)	App Todo, HotCRM	✅ Complete
UI (ObjectUI)	App Todo, HotCRM	✅ Complete
System (ObjectOS)	HotCRM	✅ Complete
Automation	App Todo, HotCRM	✅ Complete
API	HotCRM	✅ Complete
BI / Analytics	Plugin BI	🔴 Stub
Hub & Marketplace	Coming soon	🔴 Planned

🎯 Example Descriptions

App Todo

Path: examples/app-todo/
Level: 🟢 Beginner
Protocols: Data, UI, Automation

A complete task management application demonstrating all core ObjectStack protocols using the by-type directory convention.

What you'll learn:

• Object definitions with validations and workflows
• Actions (complete, defer, clone, bulk operations)
• Dashboards with 10 widgets (metrics, charts, tables)
• Reports (6 types: tabular, summary, matrix)
• Automation flows (reminders, escalation, recurring tasks)
• App navigation and branding configuration
• I18n translations (English, Chinese, Japanese)
• Package structure with objectstack.config.ts

Directory Structure:

app-todo/
├── objectstack.config.ts      # Main manifest (defineStack)
├── src/
│   ├── objects/                # Object & hook definitions
│   │   ├── task.object.ts
│   │   └── task.hook.ts
│   ├── actions/                # Action definitions
│   │   └── task.actions.ts
│   ├── apps/                   # App navigation
│   │   └── todo.app.ts
│   ├── dashboards/             # Dashboard widgets
│   │   └── task.dashboard.ts
│   ├── reports/                # Report definitions
│   │   └── task.report.ts
│   ├── flows/                  # Automation flows
│   │   └── task.flow.ts
│   └── translations/           # I18n translations (en, zh-CN, ja-JP)
│       └── todo.translation.ts
└── test/
    └── seed.test.ts

Quick Start:

cd examples/app-todo
pnpm install
pnpm typecheck

---

App Showcase

Path: examples/app-showcase/ Level: 🟣 Reference Protocols: Data, UI, System, Automation, AI, Auth

A kitchen-sink workspace built for demonstration, debugging, and coverage-driven verification. It pairs a realistic project-delivery domain with synthetic "gallery" objects that exhaust protocol variants, and ties them together with a coverage manifest that the test suite checks against the protocol's own Zod enums.

What's included:

• All 49 field types (src/objects/field-zoo.object.ts) + every relationship kind (lookup, master-detail, self-referencing tree, many-to-many junction)
• All 8 list-view types on one object (grid, kanban, gallery, calendar, timeline, gantt, map, chart) + all 5 form types
• All 38 chart types in one dashboard + all 4 report types (tabular/summary/matrix/joined)
• The action type × location matrix and a component-gallery page
• Capability chains: security (RBAC + FLS + RLS + sharing + policy), automation (flow → approval → webhook → job → email), and AI (agent + tool + skill)
• A coverage test that introspects the spec enums and fails when a new variant is left uncovered

cd examples/app-showcase
pnpm verify    # typecheck + coverage test
pnpm dev       # → http://localhost:3000/_studio

---

App CRM (external)

Repo: github.com/objectstack-ai/hotcrm Level: 🟡 Intermediate Protocols: Data, UI, Automation, AI

Full-featured CRM demonstrating enterprise-grade patterns and all major field types. The CRM example has been extracted into its own repository (HotCRM) so it can evolve independently of the framework. Clone it side-by-side to follow along with the docs:

git clone https://github.com/objectstack-ai/hotcrm.git
cd hotcrm
pnpm install
pnpm dev

What's included:

• 12 interconnected objects (Account, Contact, Opportunity, Lead, Case, Task, Campaign, Contract, Product, Quote)
• All 28 field types demonstrated
• Multiple view types (Grid, Kanban, Calendar, Gantt)
• Validation rules and workflows
• 3 dashboards (Executive, Sales, Service) plus a unified CRM overview
• 6 reports (by account, contact, lead, opportunity, case, task)
• 5 automation flows (lead conversion, case escalation, opportunity approval, etc.)
• AI agents and RAG pipelines
• Sharing rules, profiles, and role hierarchy
• I18n translations (English, Chinese, Japanese, Spanish)
• Multi-driver E2E acceptance harness (sqlite / mongodb / postgres)

---

Note: Each example app in the framework monorepo is intentionally minimal. Production-grade reference apps (HotCRM, …) live in dedicated repositories under the objectstack-ai org.

---

Plugin BI

Path: examples/plugin-bi/
Level: 🟢 Beginner
Protocols: Data, UI (Dashboards)

BI Plugin stub demonstrating how to create an ObjectStack plugin that provides analytics objects and dashboards. Currently a placeholder for adding business intelligence capabilities.

What you'll learn:

• Plugin manifest structure (type: 'plugin')
• Extending an app with analytics objects
• Dashboard widget definitions

Directory Structure:

plugin-bi/
├── objectstack.config.ts  # Plugin manifest (defineStack)
└── package.json

Quick Start:

cd examples/plugin-bi
pnpm install
pnpm typecheck

---

🗺️ Protocol Coverage Map

Data Protocol (ObjectQL)

Protocol	Example	Location
Object Definition	✅ Complete	Todo Objects, HotCRM Objects
Field Types (28 types)	✅ Complete	HotCRM Account
Validation Rules	✅ Complete	Todo, HotCRM
Relationships	✅ Complete	HotCRM Contact
Formulas	✅ Complete	HotCRM Account
Hooks	✅ Complete	Todo Hooks, HotCRM Hooks
State Machines	✅ Complete	HotCRM Lead State
Query & Filters	✅ Complete	Todo, HotCRM
Document Storage	🔴 Missing	Planned

UI Protocol (ObjectUI)

Protocol	Example	Location
List Views	✅ Complete	HotCRM - Grid, Kanban, Calendar, Gantt
Form Views	✅ Complete	HotCRM - Simple, Tabbed, Wizard
Actions	✅ Complete	Todo Actions, HotCRM Actions
Dashboards	✅ Complete	Todo Dashboard, HotCRM Dashboards
Reports	✅ Complete	Todo Reports, HotCRM Reports
Apps	✅ Complete	Todo App, HotCRM App
Charts	✅ Complete	HotCRM Dashboards
Widgets	✅ Complete	Todo Dashboard
Components	🔴 Missing	Planned

System Protocol (ObjectOS)

Protocol	Example	Location
Manifest	✅ Complete	All examples with objectstack.config.ts
Plugin System	✅ Complete	HotCRM
Preview Mode	✅ Complete	HotCRM — OS_MODE=preview
Datasources	🟡 Partial	HotCRM
I18n / Translations	✅ Complete	Todo Translations, HotCRM Translations
Job Scheduling	🔴 Missing	Planned
Metrics	🔴 Missing	Planned

AI Protocol

Protocol	Example	Location
Agent	✅ Complete	HotCRM Agents
RAG Pipeline	✅ Complete	HotCRM RAG
Model Registry	✅ Complete	Spec Only

Automation Protocol

Protocol	Example	Location
Workflow Rules	✅ Complete	Todo, HotCRM
Flow (Visual)	✅ Complete	Todo Flows, HotCRM Flows
Approval Processes	✅ Complete	HotCRM Opportunity Approval
Triggers	✅ Complete	Todo, HotCRM

Auth & Permissions

Protocol	Example	Location
Profiles	✅ Complete	HotCRM Profiles
Sharing Rules	✅ Complete	HotCRM Sharing
RBAC	🟡 Partial	HotCRM

API Protocol

Protocol	Example	Location
REST Server	✅ Complete	HotCRM
Custom APIs	✅ Complete	HotCRM APIs
GraphQL	🔴 Missing	Planned
WebSocket/Realtime	🔴 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. Explore examples
cd examples/app-todo
pnpm typecheck

# 4. Or explore the CRM (separate repository)
git clone https://github.com/objectstack-ai/hotcrm.git
cd hotcrm && pnpm install && pnpm build

Learning Path

Path 1: Quick Start (1-2 hours)

1. Read Todo Example - Understand basic structure and conventions
2. Explore Todo objectstack.config.ts - See manifest patterns
3. Browse HotCRM - Learn advanced features

Path 2: Deep Dive (1-2 days)

1. Complete Path 1
2. Study HotCRM Objects - Master field types and relationships
3. Review HotCRM Flows - Understand automation patterns

---

📝 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 (By-Type Convention)

example-name/
├── README.md              # Comprehensive documentation
├── package.json           # Package definition
├── tsconfig.json          # TypeScript config
├── objectstack.config.ts  # Main manifest (defineStack)
├── src/
│   ├── objects/           # *.object.ts, *.hook.ts, *.state.ts
│   ├── actions/           # *.actions.ts
│   ├── apps/              # *.app.ts
│   ├── dashboards/        # *.dashboard.ts
│   ├── reports/           # *.report.ts
│   ├── flows/             # *.flow.ts
│   └── translations/      # *.translation.ts (i18n bundles)
└── test/
    └── seed.test.ts

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

• Main Documentation - Complete protocol reference
• Architecture Guide - System architecture
• Quick Reference - Fast lookup
• Package Dependencies - Build order

---

📄 License

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

---

Last Updated: 2026-02-12 Protocol Version: 3.0.0 Total Examples: 2 in-repo (app-todo, plugin-bi) + 1 external (HotCRM) Directory Convention: By-Type (Salesforce DX style)