Developer Guide

This guide teaches you how to build real applications using the ObjectStack Protocol. Each section is hands-on, with code examples derived from the CRM example app.

New to ObjectStack? Start with the Example Apps to see working code, or read the Introduction for the architecture overview.

Quick Start

Create a project

npx @objectstack/cli init my-app
cd my-app

Define your first object

The scaffolded project includes a sample object. Open src/objects/my_app.ts:

import { Data } from '@objectstack/spec';

const myApp: Data.Object = {
  name: 'my_app',
  label: 'My App',
  ownership: 'own',
  fields: {
    name: {
      type: 'text',
      label: 'Name',
      required: true,
    },
    description: {
      type: 'textarea',
      label: 'Description',
    },
    status: {
      type: 'select',
      label: 'Status',
      options: [
        { label: 'Draft', value: 'draft' },
        { label: 'Active', value: 'active' },
        { label: 'Archived', value: 'archived' },
      ],
      defaultValue: 'draft',
    },
  },
};

export default myApp;

Launch the Studio

os studio

Open http://localhost:3000/_studio/ to browse your objects, test the REST API, and inspect metadata. The server automatically provides:

ObjectQL Engine — Query layer with CRUD operations
InMemory Driver — Zero-config data storage for development
Hono HTTP Server — REST API at /api/v1/{object}
Console UI — Admin interface at /_studio/

Add more metadata

os g object customer       # Generate a new object
os g action approve        # Generate an action
os g flow onboarding       # Generate an automation flow

Validate and build

os validate        # Check schema correctness
os compile         # Generate production artifact

Learning Path

Follow these guides in order for the best experience:

1. Data Modeling

Design objects, fields, relationships, and validation rules. The foundation of every app.

2. Business Logic

Implement workflows, approval flows, triggers, and formulas to automate business processes.

3. Security Model

Configure profiles, permissions, sharing rules, and row-level security for enterprise-grade access control.

4. AI Capabilities

Add AI agents, RAG pipelines, natural language queries, and predictive analytics.

5. Development Standards

Naming conventions, project structure, testing strategies, and best practices.

Project Structure

A typical ObjectStack application (generated by os init):

my-app/
├── objectstack.config.ts     # App manifest + metadata wiring
├── package.json
├── tsconfig.json
├── src/
│   ├── objects/              # Data models (required)
│   │   ├── index.ts          # Barrel export
│   │   └── my_app.ts         # Object definition
│   ├── actions/              # Buttons, batch operations
│   ├── flows/                # Automation logic
│   ├── apps/                 # Navigation definitions
│   ├── dashboards/           # Analytics dashboards
│   ├── agents/               # AI agents
│   └── rag/                  # RAG pipelines
└── test/                     # Tests

File naming conventions:

Object files: {name}.object.ts or {name}.ts (one object per file)
Action files: {name}.actions.ts
Flow files: {name}.flow.ts
Barrel exports: Each directory has an index.ts that re-exports everything

Key Concepts

Concept	Protocol	You Define	ObjectStack Provides
Data Model	ObjectQL	Objects, Fields, Validation	CRUD APIs, database schema, type safety
User Interface	ObjectUI	Views, Apps, Dashboards	React components, navigation, responsive layout
Business Logic	Automation	Flows, Workflows, Triggers	Event handlers, approval chains, scheduled jobs
Access Control	Security	Profiles, Permissions, Sharing	Middleware, RLS policies, field masking
Intelligence	AI	Agents, RAG, Models	Chat interfaces, search indexes, predictions

Next Steps

Example Apps — Run the Todo, CRM, and BI examples
Data Modeling Guide — Deep dive into objects and fields
CLI Reference — All available commands
Protocol Reference — Complete schema documentation