---
title: Developer Guide
description: Learn to build enterprise applications with the ObjectStack Protocol
---

# 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 [HotCRM reference app](https://github.com/objectstack-ai/hotcrm).

<Callout type="tip">
**New to ObjectStack?** Start with the [Example Apps](/docs/getting-started/examples) to see working code, or read the [Introduction](/docs/getting-started) for the architecture overview.
</Callout>

## Quick Start

<Steps>

### Create a project

```bash
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`:

```typescript
import { ObjectSchema, Field } from '@objectstack/spec/data';

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

export default myApp;
```

<Callout type="info">
This is the same metadata that powers the REST API, Studio editors, and the MCP tools exposed to AI agents — define it once, and ObjectStack derives the rest.
</Callout>

### Launch the Studio

```bash
os studio
```

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

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

### Add more metadata

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

### Validate, build, and run

```bash
os validate        # Check schema correctness
os compile         # Generate production artifact → dist/objectstack.json
os start           # Boot from the compiled artifact (no config file needed)
```

The compiled `dist/objectstack.json` is a portable, self-describing deployment unit — see
[CLI → Source vs Artifact](/docs/getting-started/cli#source-vs-artifact) for details.

</Steps>

## Learning Path

Follow these guides in order for the best experience:

<Cards>
  <Card
    title="1. Data Modeling"
    href="/docs/guides/data-modeling"
    description="Design objects, fields, relationships, and validation rules. The foundation of every app."
  />
  <Card
    title="2. Business Logic"
    href="/docs/guides/business-logic"
    description="Implement workflows, approval flows, triggers, and formulas to automate business processes."
  />
  <Card
    title="3. Security Model"
    href="/docs/guides/security"
    description="Configure profiles, permissions, sharing rules, and row-level security for enterprise-grade access control."
  />
  <Card
    title="4. AI Capabilities"
    href="/docs/guides/ai-capabilities"
    description="Add AI agents, RAG pipelines, natural language queries, and predictive analytics."
  />
  <Card
    title="5. Development Standards"
    href="/docs/guides/standards"
    description="Naming conventions, project structure, testing strategies, and best practices."
  />
</Cards>

## 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](/docs/getting-started/examples) &mdash; Run the Todo, CRM, and BI examples
- [Data Modeling Guide](/docs/guides/data-modeling) &mdash; Deep dive into objects and fields
- [CLI Reference](/docs/getting-started/cli) &mdash; All available commands
- [Protocol Reference](/docs/references) &mdash; Complete schema documentation
