---
title: Core Concepts
description: The foundational ideas behind ObjectStack — metadata-driven development, protocol-first design, and the principles that shape every decision
---

import { Scale, Code2, Database, ScrollText, Laptop } from 'lucide-react';

# Core Concepts

Before diving into code, understanding these foundational ideas will make everything else click.

## Metadata-Driven Development

Metadata-driven development is a paradigm shift where **application logic is defined by declarative data (metadata), not imperative code.**

### The Problem with Code-First

In traditional development, the "Intent" (e.g., *"This field is a required email address"*) is scattered across multiple layers:

1. **Database:** SQL constraints (`NOT NULL`, `CHECK`)
2. **Backend:** ORM validation (TypeORM decorators, Prisma schemas)
3. **Frontend:** UI validation (React Hook Form + Zod)
4. **Documentation:** API specs (OpenAPI/Swagger)

When a business requirement changes, you must update code in **three or four places**. This is **Implementation Coupling**.

### The ObjectStack Way

ObjectStack centralizes the "Intent" into a **single Protocol Definition**:

<Tabs items={['Array Format', 'Map Format']}>
<Tab value="Array Format">
```typescript
// ONE definition — everything else derives from it
import { defineStack } from '@objectstack/spec';

export default defineStack({
  objects: [{
    name: 'user',
    label: 'User',
    fields: {
      phone: { label: 'Phone Number', type: 'phone', required: true },
    },
  }],
});
```
</Tab>
<Tab value="Map Format">
```typescript
// Map keys become the `name` field automatically
import { defineStack } from '@objectstack/spec';

export default defineStack({
  objects: {
    user: {
      label: 'User',
      fields: {
        phone: { label: 'Phone Number', type: 'phone', required: true },
      },
    },
  },
});
```
</Tab>
</Tabs>

<Callout type="info">
**Array or Map?** `defineStack()` accepts both formats for all named metadata collections (`objects`, `apps`, `flows`, etc.). Map keys are injected as the `name` field — pick whichever style you prefer.
</Callout>

From this single definition, ObjectStack automatically:

✅ Generates database schema
✅ Creates validation rules
✅ Builds CRUD APIs
✅ Renders form fields
✅ Produces API documentation

### The Three Truths

1. **The UI is a Projection** — The form is generated from the schema, not hand-coded
2. **The API is a Consequence** — REST/GraphQL endpoints appear automatically from object definitions
3. **The Schema is the Application** — Your entire business logic lives in metadata files

### When to Use Metadata-Driven

✅ **Great for:** CRUD apps, SaaS platforms, admin panels, rapid prototyping, multi-tenant systems

❌ **Not ideal for:** Pixel-perfect custom UIs, real-time 3D/games, highly unique domains

---

## Design Principles

ObjectStack is governed by four unshakable principles:

<Cards>
  <Card
    icon={<Scale />}
    title="I. Protocol Neutrality"
    description="The Protocol is law. The Implementation is merely an opinion."
  />
  <Card
    icon={<Code2 />}
    title="II. Mechanism over Policy"
    description="Provide the tools to build rules, do not hardcode the rules themselves."
  />
  <Card
    icon={<Database />}
    title="III. Single Source of Truth"
    description="There is no 'Code'. There is only Schema."
  />
  <Card
    icon={<ScrollText />}
    title="IV. Agent-Ready Boundaries"
    description="Agents may act only through typed, permission-aware, auditable surfaces."
  />
</Cards>

### Protocol Neutrality

**"The Protocol is neutral. The Engine is replaceable."**

- **Spec before Engine:** Features must be defined in the Specification layer before any engine code is written
- **Zero Leakage:** Implementation details (React, SQL, etc.) never leak into Protocol definitions

This ensures ObjectStack apps can run on Node.js + PostgreSQL today, Python + SQLite tomorrow, or Rust WASM in the browser.

### Mechanism over Policy

**"Give them the physics, not the simulation."**

| Layer | Responsibility | Example |
| :--- | :--- | :--- |
| **Protocol** | Defines capabilities | `allowRead: string` (a slot for a formula) |
| **App** | Defines business logic | `allowRead: "$user.role == 'admin'"` |
| **Engine** | Enforces the logic | Compiles formula to SQL `WHERE` clause |

### Single Source of Truth

In ObjectStack, **the Object Protocol is the only truth:**

- The Database is a *derivative* of the Protocol
- The UI is a *projection* of the Protocol
- The API is a *consequence* of the Protocol
- The Agent tool surface is a *bounded capability set* derived from the Protocol

Change the Protocol → the entire system adapts automatically.

### Agent-Ready Boundaries

AI agents should not bypass the application model by calling raw SQL, scraping UI state, or executing arbitrary glue code. They should act through typed, permission-aware capabilities derived from the same metadata artifact that powers the application.

```
Traditional AI app: Database schema -> App code -> Custom query -> Hand-written MCP tool
ObjectStack: Zod metadata -> Environment Artifact -> ObjectStack runtime -> API / UI / MCP tools
```

---

## Naming Conventions

ObjectStack enforces strict naming rules for consistency:

| Element | Convention | Examples |
|---------|-----------|----------|
| **Object names** (machine) | `snake_case` | `todo_task`, `user_profile` |
| **Field names** (machine) | `snake_case` | `first_name`, `is_active` |
| **Export names** (constants) | `PascalCase` | `TodoTask`, `UserProfile` |
| **Config keys** (properties) | `camelCase` | `maxLength`, `defaultValue` |

## Summary

| Aspect | Traditional | Metadata-Driven |
| :--- | :--- | :--- |
| **Definition** | Code in multiple files | Single metadata definition |
| **Changes** | Update 3-4 places | Update once |
| **Type Safety** | Manual synchronization | Automatic from Zod |
| **Flexibility** | Locked to tech stack | Technology agnostic |
| **Boilerplate** | High (300+ lines) | Low (30 lines) |
| **Agent Tools** | Hand-written and drift-prone | Generated from metadata and permissions |

## Next Steps

- [Architecture](/docs/getting-started/architecture) — How the protocol layers work together
- [Quick Start](/docs/getting-started/quick-start) — Build your first app in 5 minutes
- [Glossary](/docs/getting-started/glossary) — Key terminology
