diff --git a/content/docs/getting-started/architecture.mdx b/content/docs/getting-started/architecture.mdx new file mode 100644 index 000000000..07e8d9fcc --- /dev/null +++ b/content/docs/getting-started/architecture.mdx @@ -0,0 +1,639 @@ +--- +title: Protocol Architecture +description: How the Data, System, and UI protocols work together as one cohesive system +--- + +import { Database, Layout, Cpu, ArrowRight, CheckCircle, Workflow, Bot, Cloud } from 'lucide-react'; + +# The Protocol Stack + +The architecture is built on foundational protocols that work together as a unified system: + + + } + title="Data Protocol" + description="ObjectQL: Structure, queries, and constraints." + /> + } + title="UI Protocol" + description="ObjectUI: Presentation, interaction, and routing." + /> + } + title="System Protocol" + description="ObjectOS: Control, runtime, and governance." + /> + } + title="Automation Protocol" + description="Business Logic: Flow, Workflow, Triggers." + /> + } + title="AI Protocol" + description="Intelligence: Agents, RAG, Models." + /> + } + title="Hub Protocol" + description="Management: Multi-tenancy, Marketplace, Licensing." + /> + + +## Why Separated Layers? + +Traditional applications tightly couple data, business logic, and presentation. This creates **Implementation Coupling** — changing one layer forces changes across the entire stack. + +ObjectStack enforces **Separation of Concerns** through protocol boundaries: + +``` +┌───────────────────────────────────────────────────────────┐ +│ UI Protocol & AI Protocol │ +│ Apps, Views, Dashboards, Agents, RAG │ +│ "How do users and agents interact?" │ +└───────────────────────────┬───────────────────────────────┘ + │ Interface +┌───────────────────────────┴───────────────────────────────┐ +│ System Protocol & Automation Protocol & Hub Protocol │ +│ Auth, Permissions, Orchestration, Multi-tenancy │ +│ "Who/What can do what, when, and where?" │ +└───────────────────────────┬───────────────────────────────┘ + │ Control +┌───────────────────────────┴───────────────────────────────┐ +│ Data Protocol │ +│ Objects, Fields, Queries, Drivers │ +│ "What is the data structure?" │ +└───────────────────────────────────────────────────────────┘ +``` + +## Layer 1: ObjectQL (Data Protocol) + +**Role:** Define the **Structure** and **Intent** of data. + +**Responsibilities:** +- Object schema definitions (what is a "Customer"?) +- Field types and validation rules +- Query language (filtering, sorting, aggregation) +- Database drivers (Postgres, MongoDB, SQLite) + +**Key Principle:** ObjectQL knows **nothing** about users, permissions, or UI. It only cares about data structure and queries. + +### Example: Defining a Customer Object + +```typescript +// packages/crm/src/objects/customer.object.ts +import { ObjectSchema, Field } from '@objectstack/spec/data'; + +export const Customer = ObjectSchema.create({ + name: 'customer', + label: 'Customer', + icon: 'building', + + fields: { + name: Field.text({ + label: 'Company Name', + required: true, + maxLength: 120, + }), + + industry: Field.select({ + label: 'Industry', + options: [ + { label: 'Technology', value: 'technology' }, + { label: 'Finance', value: 'finance' }, + { label: 'Healthcare', value: 'healthcare' }, + { label: 'Retail', value: 'retail' }, + ], + }), + + annual_revenue: Field.currency({ + label: 'Annual Revenue', + scale: 2, + }), + + primary_contact: Field.lookup('contact', { + label: 'Primary Contact', + }), + }, +}); +``` + +This definition is **pure metadata**. It doesn't know: +- Who can see this data +- How to render a form +- When to trigger workflows + +That's the job of the other layers. + +## Layer 2: ObjectOS (Control Protocol) + +**Role:** Manage the **Lifecycle** and **Governance** of requests. + +**Responsibilities:** +- Authentication (who is this user?) +- Authorization (can they access this field?) +- Workflows and automations (what happens after save?) +- Event processing (audit logs, notifications) +- Multi-tenancy and data isolation + +**Key Principle:** ObjectOS acts as the **Gateway**. No layer can directly access the database; all requests must pass through the OS Kernel. + +### Example: Permission Rules + +```typescript +// packages/crm/src/permissions/customer.permission.ts +import { Permission } from '@objectstack/spec'; + +export const CustomerPermission = Permission({ + object: 'customer', + rules: [ + { + profile: 'sales_rep', + crud: { + create: true, + read: true, + update: true, + delete: false, // Only managers can delete + }, + fieldPermissions: { + annual_revenue: { read: true, edit: false }, // Read-only + }, + }, + { + profile: 'sales_manager', + crud: { + create: true, + read: true, + update: true, + delete: true, + }, + }, + ], +}); +``` + +### Example: Workflow Automation + +```typescript +// packages/crm/src/workflows/customer.workflow.ts +import { Workflow } from '@objectstack/spec'; + +export const CustomerWorkflow = Workflow({ + object: 'customer', + trigger: 'after_create', + conditions: [ + { field: 'annual_revenue', operator: 'greaterThan', value: 1000000 }, + ], + actions: [ + { + type: 'assign_owner', + params: { owner: 'enterprise_sales_team' }, + }, + { + type: 'send_email', + params: { + template: 'high_value_customer_alert', + to: 'sales-leadership@company.com', + }, + }, + ], +}); +``` + +ObjectOS **orchestrates** these rules at runtime, independent of the data structure or UI. + +## Layer 3: ObjectUI (View Protocol) + +**Role:** Render the **Presentation** and handle **User Interaction**. + +**Responsibilities:** +- App navigation and branding +- List views (grid, kanban, calendar) +- Form layouts (simple, tabbed, wizard) +- Dashboards and reports +- Actions and buttons + +**Key Principle:** ObjectUI is a **Rendering Engine**, not a hardcoded interface. It asks ObjectQL *"What is the schema?"* and dynamically generates the UI. + +### Example: List View + +```typescript +// packages/crm/src/views/customer_list.view.ts +import { ListView } from '@objectstack/spec'; + +export const CustomerListView = ListView({ + object: 'customer', + label: 'All Customers', + type: 'grid', + columns: [ + { field: 'name', width: 200 }, + { field: 'industry', width: 150 }, + { field: 'annual_revenue', width: 150 }, + { field: 'primary_contact', width: 180 }, + ], + filters: [ + { field: 'industry', operator: 'equals' }, + { field: 'annual_revenue', operator: 'greaterThan' }, + ], + defaultSort: { field: 'name', direction: 'asc' }, +}); +``` + +### Example: Form View + +```typescript +// packages/crm/src/views/customer_form.view.ts +import { FormView } from '@objectstack/spec'; + +export const CustomerFormView = FormView({ + object: 'customer', + label: 'Customer Details', + type: 'tabbed', + tabs: [ + { + label: 'Overview', + sections: [ + { + label: 'Company Information', + fields: ['name', 'industry', 'annual_revenue'], + }, + { + label: 'Contact', + fields: ['primary_contact'], + }, + ], + }, + { + label: 'Related Records', + sections: [ + { + label: 'Opportunities', + component: 'related_list', + object: 'opportunity', + filter: { customer: '$recordId' }, + }, + ], + }, + ], +}); +``` + +The UI doesn't "know" the field types. It asks ObjectQL for the schema and renders accordingly: +- `Field.text` → Text input +- `Field.select` → Dropdown +- `Field.lookup` → Autocomplete lookup +- `Field.currency` → Number input with currency formatting + +## How They Work Together + +Let's trace a **real-world scenario**: A sales rep creates a new high-value customer. + +### Step 1: User Action (ObjectUI) + +``` +User fills out the "Create Customer" form: +- Name: "Acme Corp" +- Industry: "Technology" +- Annual Revenue: $5,000,000 +- Primary Contact: "John Doe" + +User clicks "Save" +``` + +### Step 2: UI Layer Sends Request + +```typescript +// ObjectUI dispatches an action to ObjectOS +const request = { + action: 'create', + object: 'customer', + data: { + name: 'Acme Corp', + industry: 'technology', + annual_revenue: 5000000, + primary_contact: 'contact_12345', + }, +}; +``` + +### Step 3: ObjectOS Validates Permissions + +```typescript +// Kernel checks: Does this user have permission? +const user = await Auth.getCurrentUser(); +const canCreate = await Permission.check({ + user, + object: 'customer', + operation: 'create', +}); + +if (!canCreate) { + throw new Error('Permission denied'); +} +``` + +### Step 4: ObjectOS Validates Data + +```typescript +// Kernel asks ObjectQL: Is this data valid? +const schema = ObjectQL.getSchema('customer'); +const validation = schema.validate(request.data); + +if (!validation.success) { + throw new ValidationError(validation.errors); +} +``` + +### Step 5: ObjectQL Writes to Database + +```typescript +// ObjectQL compiles the request into a database operation +const driver = ObjectQL.getDriver(); // Postgres, MongoDB, etc. +const result = await driver.insert('customer', { + name: 'Acme Corp', + industry: 'technology', + annual_revenue: 5000000, + primary_contact_id: 'contact_12345', +}); +``` + +### Step 6: ObjectOS Triggers Workflows + +```typescript +// Kernel checks: Are there any workflows for this event? +const workflows = Workflow.getTriggersFor('customer', 'after_create'); + +for (const workflow of workflows) { + if (workflow.conditionsMet(result)) { + await workflow.execute(result); + } +} + +// In this case: +// ✅ Annual revenue > $1M +// → Assign to enterprise sales team +// → Send alert email to leadership +``` + +### Step 7: ObjectUI Updates Display + +```typescript +// Kernel returns success response +// UI optimistically updates the screen +// UI shows toast notification: "Customer created successfully" +// UI navigates to the new customer detail page +``` + +## The Full Stack in Action + +Here's how all three protocols collaborate for a **Kanban Board** feature: + +### 1. ObjectQL: Define the Data + +```typescript +import { ObjectSchema, Field } from '@objectstack/spec/data'; + +export const Opportunity = ObjectSchema.create({ + name: 'opportunity', + label: 'Opportunity', + icon: 'target', + + fields: { + title: Field.text({ + label: 'Title', + required: true, + }), + + stage: Field.select({ + label: 'Stage', + options: [ + { label: 'Prospecting', value: 'prospecting', default: true }, + { label: 'Qualification', value: 'qualification' }, + { label: 'Proposal', value: 'proposal' }, + { label: 'Closed Won', value: 'closed_won' }, + ], + }), + + amount: Field.currency({ + label: 'Amount', + scale: 2, + }), + + customer: Field.lookup('customer', { + label: 'Customer', + }), + }, +}); +``` + +### 2. ObjectOS: Define Business Rules + +```typescript +export const OpportunityWorkflow = Workflow({ + object: 'opportunity', + trigger: 'field_update', + conditions: [ + { field: 'stage', operator: 'equals', value: 'closed_won' }, + ], + actions: [ + { type: 'create_invoice', params: { object: 'invoice' } }, + { type: 'send_notification', params: { to: 'sales_team' } }, + ], +}); +``` + +### 3. ObjectUI: Define the Kanban View + +```typescript +export const OpportunityKanban = ListView({ + object: 'opportunity', + type: 'kanban', + groupBy: 'stage', + columns: [ + { field: 'title' }, + { field: 'amount' }, + { field: 'customer' }, + ], + enableDragDrop: true, +}); +``` + +### The Result + +When a user **drags an opportunity card** from "Proposal" to "Closed Won": + +1. **ObjectUI** captures the drag-drop event +2. **ObjectOS** checks if the user has permission to update the `stage` field +3. **ObjectQL** validates that `"closed_won"` is a valid option +4. **ObjectQL** writes the update to the database +5. **ObjectOS** triggers the workflow (create invoice, send notification) +6. **ObjectUI** updates the kanban board to reflect the new state + +**All from metadata. Zero hardcoded logic.** + +## Benefits of the Three-Layer Architecture + +### 1. Technology Independence + +Swap implementations without breaking the system: + +``` +Same Metadata Definitions + ↓ +┌─────────┼─────────┐ +ObjectQL: │ │ +Postgres │ MongoDB + │ +ObjectOS: │ +Node.js │ Python + │ +ObjectUI: │ +React │ Flutter +``` + +### 2. Parallel Development + +Teams can work independently on each layer: + +- **Data Team:** Define objects in ObjectQL +- **Backend Team:** Build workflows in ObjectOS +- **Frontend Team:** Create views in ObjectUI + +All communicate through **protocol contracts**, not code dependencies. + +### 3. Incremental Migration + +Adopt ObjectStack gradually: + +- **Phase 1:** Use ObjectQL as an ORM replacement +- **Phase 2:** Add ObjectOS for permissions and workflows +- **Phase 3:** Build ObjectUI views to replace custom forms + +Each layer is independently useful. + +### 4. Testability + +Mock any layer for testing: + +```typescript +// Test ObjectOS workflows without a real database +const mockObjectQL = { + getSchema: () => CustomerSchema, + insert: jest.fn(), +}; + +// Test ObjectUI rendering without a real backend +const mockObjectOS = { + checkPermission: () => true, + executeQuery: () => mockData, +}; +``` + +## Summary + +| Layer | Role | Knows About | Doesn't Know About | +| :--- | :--- | :--- | :--- | +| **ObjectQL** | Data structure & queries | Schema, fields, drivers | Users, permissions, UI | +| **ObjectOS** | Runtime & governance | Auth, workflows, events | Data structure, UI layout | +| **ObjectUI** | Presentation & interaction | Layout, navigation, actions | Business logic, data storage | + +The three protocols are **loosely coupled** but **tightly integrated**: +- They communicate through **standard contracts** (Zod schemas) +- They can be **swapped or upgraded** independently +- They form a **complete system** when combined + +## Next Steps + +- [ObjectQL: Data Protocol](/docs/protocol/objectql) - Full data protocol specification +- [ObjectUI: UI Protocol](/docs/protocol/objectui) - Full view protocol specification +- [ObjectOS: System Protocol](/docs/protocol/objectos) - Full control protocol specification +- [Developer Guide](/docs/getting-started/quick-start) - Build your first ObjectStack application + +--- + +## Appendix: Protocol Dependencies + +Understanding the dependency chain helps you design applications correctly. + +### Data Layer (ObjectQL) + +``` +Field Protocol (Core) + ↓ + ├→ Object Protocol (uses Fields) + ├→ Query Protocol (references Fields) + ├→ Filter Protocol (filters on Fields) + └→ Validation Protocol (validates Fields) + ↓ + └→ Hook Protocol (extends validation with code) +``` + +### UI Layer (ObjectUI) + +``` +Theme Protocol (Foundation) + ↓ +View Protocol (uses Object, Query) + ├→ ListView (uses Query, Filter) + ├→ FormView (uses Object, Field) + └→ Dashboard (uses View, Widget) + ↓ + ├→ Page Protocol (composes Views) + └→ App Protocol (organizes Pages) + ↓ + └→ Action Protocol (UI interactions) +``` + +### System Layer (ObjectOS) + +``` +Driver Protocol (Database Abstraction) + ↓ +Datasource Protocol (Connection Config) + ↓ + ├→ Context Protocol (Runtime State) + ├→ Events Protocol (Event Bus) + └→ Plugin Protocol (Extensibility) + ↓ + ├→ Security Protocol (Access Control) + ├→ API Protocol (External Access) + └→ Automation Protocol (Workflows) + ↓ + └→ AI Protocol (Intelligence) +``` + +## Appendix: Usage Patterns + +### Pattern 1: Data-Driven UI + +UI auto-generated from data definitions: + +``` +Object → Field → View → Page → App +``` + +### Pattern 2: Custom UI with Data Binding + +Custom UI connected to data: + +``` +Page → Component → View (Custom) → Query → Object +``` + +### Pattern 3: Automation & Integration + +Business logic automation: + +``` +Object → Hook → Flow → Automation → API/Webhook +``` + +### Pattern 4: AI-Enhanced Applications + +AI capabilities on top of data: + +``` +Object → RAG Pipeline → Agent → Conversation → UI +``` diff --git a/content/docs/getting-started/core-concepts.mdx b/content/docs/getting-started/core-concepts.mdx new file mode 100644 index 000000000..a71967f76 --- /dev/null +++ b/content/docs/getting-started/core-concepts.mdx @@ -0,0 +1,160 @@ +--- +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**: + +```typescript +// ONE definition — everything else derives from it +import { defineStack } from '@objectstack/spec'; + +export default defineStack({ + objects: [{ + name: 'user', + label: 'User', + fields: [ + { name: 'phone', label: 'Phone Number', type: 'phone', required: true }, + ], + }], +}); +``` + +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: + + + } + title="I. Protocol Neutrality" + description="The Protocol is law. The Implementation is merely an opinion." + /> + } + title="II. Mechanism over Policy" + description="Provide the tools to build rules, do not hardcode the rules themselves." + /> + } + title="III. Single Source of Truth" + description="There is no 'Code'. There is only Schema." + /> + } + title="IV. Local-First by Default" + description="The Cloud is a sync peer, not a master." + /> + + +### 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 + +Change the Protocol → the entire system adapts automatically. + +### Local-First by Default + +All interactions should be instant (0ms latency). The user's data lives on their device; the server is a sync hub. + +``` +Traditional: Click → Wi-Fi → ISP → Cloud → DB → Response +Local-First: Click → Local DB → UI Update (0ms) +``` + +--- + +## 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) | + +## 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 diff --git a/content/docs/getting-started/glossary.mdx b/content/docs/getting-started/glossary.mdx new file mode 100644 index 000000000..edef2a76f --- /dev/null +++ b/content/docs/getting-started/glossary.mdx @@ -0,0 +1,125 @@ +--- +title: Glossary +description: The Glossary of the ObjectStack Ecosystem. Speaking the same language. +--- + +import { Book, Server, Code, Database } from 'lucide-react'; + +To navigate the ObjectStack ecosystem effectively, it is helpful to understand the specific vocabulary we use. While many terms are standard in computer science, some have specific nuances in our "Protocol-Driven" context. + +## The Ecosystem + +### ObjectStack +The umbrella term for the entire suite of protocols and reference implementations. It is organized into **11 protocol namespaces** grouped into three architectural layers. + +### Protocol Namespace +A logical grouping of related schemas and types defined with Zod. ObjectStack has 11 protocol namespaces: Data, Driver, Permission, UI, System, Auth, Kernel, Hub, AI, API, and Automation. + +--- + +## The 11 Protocol Namespaces + +### Data Protocol +Defines the core business data model. Includes Object schema, Field types, Validation rules, Query AST, and Filter conditions. This is the foundation of ObjectQL. + +### Driver Protocol +Database adapter interface for connecting to various storage engines (PostgreSQL, MongoDB, SQLite, Redis, etc.). Drivers implement a standard interface for CRUD operations and query execution. + +### Permission Protocol +Access control system including object-level permissions (CRUD), field-level security (FLS), sharing rules, and territory management. Determines who can see and modify what data. + +### UI Protocol +Server-Driven UI specification for building user interfaces. Includes App structure, Views (List/Form/Kanban/Calendar), Dashboards, Reports, Themes, and Actions. + +### System Protocol +Infrastructure services including Event Bus, Job Scheduling, Translation (i18n), and Audit Logging. Manages system-level concerns. + +### Auth Protocol +Identity and access management including User accounts, Sessions, Roles, Organization structure, and various authentication strategies (OAuth, SAML, LDAP, etc.). + +### Kernel Protocol +Plugin system and runtime management. Includes Plugin lifecycle, Manifest definition, Logger configuration, and Runtime Context. The core of ObjectOS. + +### Hub Protocol +SaaS and marketplace features including Multi-tenancy, Licensing, Marketplace plugins, and Deployment configurations. Enables commercial distribution. + +### AI Protocol +Artificial intelligence capabilities including AI Agents, RAG pipelines, Natural Language Query (NLQ), Predictive models, Cost tracking, and Orchestration. + +### API Protocol +External communication layer including REST contracts, API discovery, Realtime subscriptions (WebSocket/SSE), and Routing configuration. + +### Automation Protocol +Business process automation including Workflows (state machines), Flows (visual logic), and Webhooks (HTTP callbacks). + +--- + +## Architecture Concepts + +### Protocol-Driven +A development paradigm where logic is defined in static, declarative data formats (JSON/YAML) with Zod schemas rather than imperative code. The goal is to separate the **Intent** (Business Logic) from the **Implementation** (Tech Stack). + +### Local-First +An architectural pattern where the application reads and writes to a database embedded on the user's device (the Client) first. Network synchronization happens in the background. This ensures zero-latency interactions and offline availability. + +### Database Compiler +A system that takes a high-level query AST (Abstract Syntax Tree) and compiles it into an optimized database query string (e.g., SQL). This contrasts with an ORM, which typically acts as a runtime wrapper object. + +### Virtual Field +A field defined in the Data Protocol schema that does not exist physically in the database table but is computed on the fly. +* *Example:* A SQL subquery or expression injected into the `SELECT` statement at compile time. + +--- + +## Data & Schema + +### Object (Entity) +The fundamental unit of data modeling in ObjectStack. Roughly equivalent to a "Table" in SQL or a "Collection" in NoSQL. An Object definition includes Fields, Actions, Triggers, and Permissions. + +### Driver +An adapter plugin (Driver Protocol) that allows the Data Layer to communicate with a specific underlying storage engine. +* *Example:* `@objectstack/driver-postgres`, `@objectstack/driver-mongodb`, `@objectstack/driver-sqlite`. + +### AST (Abstract Syntax Tree) +The intermediate representation of a query or schema. The Data Protocol parses a JSON request into an AST before the Driver translates it into SQL/NoSQL queries. This allows for security validation and optimization before execution. + +### Manifest +The entry point configuration file (Kernel Protocol) for an ObjectStack Plugin. It declares dependencies, resources, and extensions using the Manifest schema. + +--- + +## Interface & Logic + +### Layout +A JSON structure defined in the UI Protocol that describes the visual arrangement of components. Layouts can be nested and dynamic (e.g., Master-Detail, Grid, Kanban). + +### Workflow +A business process (Automation Protocol) defined as a **Finite State Machine (FSM)**. It consists of States (e.g., `draft`, `approved`), Transitions, and Guards. + +### Flow +A visual logic automation tool (Automation Protocol) that allows building business processes using a node-based editor. Supports screen flows, autolaunched flows, and scheduled flows. + +### Action +A discrete unit of logic (UI Protocol) that can be triggered by a user (UI button) or a system event (Workflow transition). Actions define button behaviors and navigation. + +### Component Registry +A map within the UI Runtime that links a string identifier (e.g., `"chart.bar"`) to a real React Component. This allows the UI Protocol to instantiate UI elements dynamically. + +--- + +## Governance + +### Space (Workspace) +A logical isolation unit (Hub Protocol) for multi-tenancy. A single ObjectStack instance can host multiple Spaces. Data is physically segregated by tenant isolation strategies. + +### FLS (Field-Level Security) +A granular permission model (Permission Protocol) where access control is applied to individual fields (columns), not just the whole object (row). + +### OWD (Organization-Wide Defaults) +The default sharing level (Permission Protocol) for records in an object. Determines the baseline access level before sharing rules are applied. + +### Territory +A hierarchical access control model (Permission Protocol) that grants data access based on geographic or organizational boundaries. + +### TCK (Technology Compatibility Kit) +A suite of tests that validates if a Driver or Renderer complies with the official ObjectStack Protocol. If a new driver passes the TCK, it is certified as compatible. diff --git a/content/docs/getting-started/index.mdx b/content/docs/getting-started/index.mdx index 3817b3118..b36f343ed 100644 --- a/content/docs/getting-started/index.mdx +++ b/content/docs/getting-started/index.mdx @@ -137,7 +137,7 @@ For more troubleshooting, see the [Troubleshooting & FAQ](/docs/guides/troublesh ## Next Steps -- [Design Principles](/docs/concepts/design-principles) - Understand the philosophy -- [Architecture](/docs/concepts/architecture) - Deep dive into the system -- [Glossary](/docs/concepts/terminology) - Learn key terminology -- [Core Concepts](/docs/core-concepts) - Metadata-driven development explained +- [Core Concepts](/docs/getting-started/core-concepts) — Metadata-driven development & design principles +- [Architecture](/docs/getting-started/architecture) — The three-layer protocol stack +- [Glossary](/docs/getting-started/glossary) — Key terminology +- [Quick Start](/docs/getting-started/quick-start) — Build your first app in 5 minutes diff --git a/content/docs/getting-started/meta.json b/content/docs/getting-started/meta.json index 43ae066ec..d15443e51 100644 --- a/content/docs/getting-started/meta.json +++ b/content/docs/getting-started/meta.json @@ -1,4 +1,4 @@ { "title": "Getting Started", - "pages": ["index", "quick-start", "examples", "cli"] + "pages": ["index", "quick-start", "core-concepts", "architecture", "examples", "cli", "glossary"] } diff --git a/content/docs/getting-started/quick-start.mdx b/content/docs/getting-started/quick-start.mdx index 56380be27..efedc20e6 100644 --- a/content/docs/getting-started/quick-start.mdx +++ b/content/docs/getting-started/quick-start.mdx @@ -96,27 +96,27 @@ Follow these guides in order for the best experience: diff --git a/content/docs/guides/backward-compatibility.mdx b/content/docs/guides/cheatsheets/backward-compatibility.mdx similarity index 100% rename from content/docs/guides/backward-compatibility.mdx rename to content/docs/guides/cheatsheets/backward-compatibility.mdx diff --git a/content/docs/guides/error-catalog.mdx b/content/docs/guides/cheatsheets/error-catalog.mdx similarity index 99% rename from content/docs/guides/error-catalog.mdx rename to content/docs/guides/cheatsheets/error-catalog.mdx index 523a96477..fa0284b5a 100644 --- a/content/docs/guides/error-catalog.mdx +++ b/content/docs/guides/cheatsheets/error-catalog.mdx @@ -103,7 +103,7 @@ ObjectStack uses a structured error system with **9 error categories** and **41+ ### `invalid_query` **Cause:** The query structure is malformed. -**Fix:** Check the query syntax against the [Query Cheat Sheet](/references/data/query-cheat-sheet). +**Fix:** Check the query syntax against the [Query Cheat Sheet](/docs/guides/cheatsheets/query-cheat-sheet). **Retry:** `no_retry` ### `invalid_filter` diff --git a/content/docs/guides/field-type-decision-tree.mdx b/content/docs/guides/cheatsheets/field-type-decision-tree.mdx similarity index 98% rename from content/docs/guides/field-type-decision-tree.mdx rename to content/docs/guides/cheatsheets/field-type-decision-tree.mdx index 86d0402e2..42b5cf2be 100644 --- a/content/docs/guides/field-type-decision-tree.mdx +++ b/content/docs/guides/cheatsheets/field-type-decision-tree.mdx @@ -8,7 +8,7 @@ description: Interactive guide for choosing the right ObjectStack field type — Not sure which field type to use? Follow this decision tree to find the right type for your data, then check the quick-reference table for details. -**Full Details:** Once you've identified the right type, see the [Field Type Gallery](/references/data/field-type-gallery) for complete configuration properties. +**Full Details:** Once you've identified the right type, see the [Field Type Gallery](/docs/guides/cheatsheets/field-type-gallery) for complete configuration properties. --- diff --git a/content/docs/guides/field-type-gallery.mdx b/content/docs/guides/cheatsheets/field-type-gallery.mdx similarity index 100% rename from content/docs/guides/field-type-gallery.mdx rename to content/docs/guides/cheatsheets/field-type-gallery.mdx diff --git a/content/docs/guides/field-validation-rules.mdx b/content/docs/guides/cheatsheets/field-validation-rules.mdx similarity index 100% rename from content/docs/guides/field-validation-rules.mdx rename to content/docs/guides/cheatsheets/field-validation-rules.mdx diff --git a/content/docs/guides/cheatsheets/meta.json b/content/docs/guides/cheatsheets/meta.json new file mode 100644 index 000000000..092c1573c --- /dev/null +++ b/content/docs/guides/cheatsheets/meta.json @@ -0,0 +1,15 @@ +{ + "title": "Cheatsheets", + "pages": [ + "quick-reference", + "field-type-gallery", + "field-type-decision-tree", + "field-validation-rules", + "query-cheat-sheet", + "error-catalog", + "wire-format", + "protocol-diagram", + "permissions-matrix", + "backward-compatibility" + ] +} diff --git a/content/docs/guides/permissions-matrix.mdx b/content/docs/guides/cheatsheets/permissions-matrix.mdx similarity index 100% rename from content/docs/guides/permissions-matrix.mdx rename to content/docs/guides/cheatsheets/permissions-matrix.mdx diff --git a/content/docs/guides/protocol-diagram.mdx b/content/docs/guides/cheatsheets/protocol-diagram.mdx similarity index 100% rename from content/docs/guides/protocol-diagram.mdx rename to content/docs/guides/cheatsheets/protocol-diagram.mdx diff --git a/content/docs/guides/query-cheat-sheet.mdx b/content/docs/guides/cheatsheets/query-cheat-sheet.mdx similarity index 100% rename from content/docs/guides/query-cheat-sheet.mdx rename to content/docs/guides/cheatsheets/query-cheat-sheet.mdx diff --git a/content/docs/guides/quick-reference.mdx b/content/docs/guides/cheatsheets/quick-reference.mdx similarity index 100% rename from content/docs/guides/quick-reference.mdx rename to content/docs/guides/cheatsheets/quick-reference.mdx diff --git a/content/docs/guides/wire-format.mdx b/content/docs/guides/cheatsheets/wire-format.mdx similarity index 98% rename from content/docs/guides/wire-format.mdx rename to content/docs/guides/cheatsheets/wire-format.mdx index 0ff7d71de..44adbe90f 100644 --- a/content/docs/guides/wire-format.mdx +++ b/content/docs/guides/cheatsheets/wire-format.mdx @@ -425,7 +425,7 @@ All errors follow a consistent structure defined by `ErrorResponseSchema`. ``` -**Error Codes:** See the [Error Catalog](/references/api/error-catalog) for the complete list of error codes and their meanings. +**Error Codes:** See the [Error Catalog](/docs/guides/cheatsheets/error-catalog) for the complete list of error codes and their meanings. --- diff --git a/content/docs/guides/common-patterns.mdx b/content/docs/guides/common-patterns.mdx index 8b7a687c5..57877da04 100644 --- a/content/docs/guides/common-patterns.mdx +++ b/content/docs/guides/common-patterns.mdx @@ -432,7 +432,7 @@ export default defineStack({ **Next Steps:** -- [Field Type Gallery](/references/data/field-type-gallery) — Choose the right field type -- [Query Cheat Sheet](/references/data/query-cheat-sheet) — Write powerful queries -- [Error Catalog](/references/api/error-catalog) — Handle errors gracefully +- [Field Type Gallery](/docs/guides/cheatsheets/field-type-gallery) — Choose the right field type +- [Query Cheat Sheet](/docs/guides/cheatsheets/query-cheat-sheet) — Write powerful queries +- [Error Catalog](/docs/guides/cheatsheets/error-catalog) — Handle errors gracefully diff --git a/content/docs/guides/data-flow.mdx b/content/docs/guides/data-flow.mdx index 2cf5eebbb..1bd32a386 100644 --- a/content/docs/guides/data-flow.mdx +++ b/content/docs/guides/data-flow.mdx @@ -8,7 +8,7 @@ description: How data moves through the ObjectStack system — from defineStack( This guide provides detailed diagrams showing how data moves through every layer of the ObjectStack system — from developer configuration to database operations and back to the client. -**Architecture Overview:** For a high-level view of how protocol layers connect, see the [Protocol Relationship Diagram](/references/data/protocol-diagram). +**Architecture Overview:** For a high-level view of how protocol layers connect, see the [Protocol Relationship Diagram](/docs/guides/cheatsheets/protocol-diagram). --- diff --git a/content/docs/guides/error-handling-client.mdx b/content/docs/guides/error-handling-client.mdx index 14554acce..2088bd774 100644 --- a/content/docs/guides/error-handling-client.mdx +++ b/content/docs/guides/error-handling-client.mdx @@ -8,7 +8,7 @@ description: Best practices for handling ObjectStack errors in client applicatio This guide covers best practices for handling ObjectStack API errors in client applications — from parsing error responses to displaying validation errors in forms and implementing retry strategies. -**Error Format:** All ObjectStack API errors follow the `ErrorResponseSchema` structure. See [Wire Format](/references/api/wire-format#7-error-response-format) for the full JSON shape. +**Error Format:** All ObjectStack API errors follow the `ErrorResponseSchema` structure. See [Wire Format](/docs/guides/cheatsheets/wire-format#7-error-response-format) for the full JSON shape. --- diff --git a/content/docs/guides/index.mdx b/content/docs/guides/index.mdx index 532597c15..3e7cf57a5 100644 --- a/content/docs/guides/index.mdx +++ b/content/docs/guides/index.mdx @@ -1,50 +1,71 @@ --- title: Guides -description: Step-by-step tutorials for building with ObjectStack +description: Task-oriented tutorials for building applications with ObjectStack --- +import { Database, Workflow, Shield, Bot, Globe, Wrench, BookMarked, FileText } from 'lucide-react'; + # Developer Guides -Practical tutorials covering the full development workflow — from data modeling to production deployment. - -These guides assume you've completed the [Quick Start](/docs/getting-started/quick-start) tutorial. - -## Key Components - -### 1. The Core Kernel -The `@objectstack/core` package is the microkernel that provides: -- **Plugin System**: Dynamic loading and lifecycle management. -- **Dependency Injection**: Service registration and resolution. -- **Event Bus**: System-wide event emission and handling. - -### 2. The Runtime Support -The `@objectstack/runtime` package implements the universal `HttpDispatcher` and server logic: -- **Unified Dispatcher**: Handles Data, UI, and Auth requests via a standard interface. -- **Protocol Adapter**: Adapts HTTP requests (Hono, Next.js, NestJS) to internal protocol calls. - -### 3. The Developer Toolchain -The `@objectstack/cli` provides a complete development workflow: -- **Scaffolding**: `os init` and `os generate` for project and metadata creation. -- **Plugin Management**: `os plugin add/remove/list` for managing plugins. -- **Validation**: `os validate` for schema checking with `--strict` and `--json` modes. -- **Introspection**: `os info` for metadata summary and `os doctor` for environment health. -- **Build**: `os compile` for production artifact generation. -- **Server**: `os serve` and `os dev` for development with auto-plugin detection. - -### 4. The Client Ecosystem -- **Frontend Integration**: `@objectstack/client` and `@objectstack/client-react` for building UIs. -- **Query Builder**: Type-safe query construction with `QueryBuilder` and `FilterBuilder`. - -## Documentation Structure - -- **[Metadata Types](./metadata)**: Comprehensive guide to every metadata type used in application development — Object, Field, View, Page, App, Dashboard, Flow, Workflow, Validation, and Permission. -- **[Data Modeling](./data-modeling)**: Best practices for designing robust data models. -- **[Business Logic](./business-logic)**: Automation, workflows, and custom logic. -- **[Plugins](./plugins)**: Building and extending the platform with plugins. -- **[Authentication](./authentication)**: Authentication and identity management. -- **[Security](./security)**: Access control, permissions, and row-level security. -- **[AI Capabilities](./ai-capabilities)**: AI agents, RAG pipelines, and model integration. -- **[API Reference](./api-reference)**: REST, GraphQL, and WebSocket APIs. -- **[Client SDK](./client-sdk)**: TypeScript client and React hooks documentation. -- **[Driver Configuration](./driver-configuration)**: Database driver setup and configuration. -- **[Kernel Services](./kernel-services)**: Core microkernel architecture and services. +Practical, task-oriented guides covering the full development workflow. Each guide is self-contained — jump to whatever you need. + + +**New here?** Complete the [Quick Start](/docs/getting-started/quick-start) first, then return here to go deeper. + + +## Foundations + + + } + title="Metadata Types" + href="/docs/guides/metadata" + description="Every metadata type: Object, Field, View, App, Dashboard, Flow, Workflow, Validation, Permission." + /> + } + title="Data Modeling" + href="/docs/guides/data-modeling" + description="Design objects, fields, relationships, indexes, and validation rules." + /> + } + title="Common Patterns" + href="/docs/guides/common-patterns" + description="Top 10 copy-paste patterns: CRUD, search, auth, realtime, and more." + /> + + +## Building Applications + +| Guide | What You'll Learn | +| :--- | :--- | +| [Plugins](/docs/guides/plugins) | Using and configuring plugins | +| [Plugin Development](/docs/guides/plugin-development) | Building, testing, and publishing plugins | +| [Business Logic](/docs/guides/business-logic) | Workflows, approval flows, triggers, formulas | +| [Authentication](/docs/guides/authentication) | Identity management, OAuth, SAML, sessions | +| [Security](/docs/guides/security) | Profiles, permissions, sharing rules, RLS | +| [AI Capabilities](/docs/guides/ai-capabilities) | AI agents, RAG pipelines, NLQ, models | + +## Integration & Infrastructure + +| Guide | What You'll Learn | +| :--- | :--- | +| [API Reference](/docs/guides/api-reference) | REST, GraphQL, and WebSocket APIs | +| [Client SDK](/docs/guides/client-sdk) | TypeScript client and React hooks | +| [Driver Configuration](/docs/guides/driver-configuration) | Database driver setup (Postgres, MongoDB, SQLite) | +| [Kernel Services](/docs/guides/kernel-services) | Microkernel architecture and service registry | +| [Data Flow](/docs/guides/data-flow) | Request lifecycle and data flow diagrams | + +## Operations + +| Guide | What You'll Learn | +| :--- | :--- | +| [Error Handling (Client)](/docs/guides/error-handling-client) | Frontend error handling patterns | +| [Error Handling (Server)](/docs/guides/error-handling-server) | Backend error handling and recovery | +| [Development Standards](/docs/guides/standards) | Naming conventions, project structure, testing | +| [Troubleshooting](/docs/guides/troubleshooting) | FAQ and solutions to common issues | + +## Quick Reference + +Need to look something up fast? See the [Cheatsheets](/docs/guides/cheatsheets) — field types, query syntax, error codes, and more. diff --git a/content/docs/guides/meta.json b/content/docs/guides/meta.json index 194cf8c78..957f9423d 100644 --- a/content/docs/guides/meta.json +++ b/content/docs/guides/meta.json @@ -5,32 +5,26 @@ "metadata", "data-modeling", "common-patterns", + "---Building---", "plugins", "plugin-development", "business-logic", "authentication", "security", "ai-capabilities", + "---Integration---", "api-reference", "client-sdk", "driver-configuration", "kernel-services", "data-flow", - "standards", - "troubleshooting", + "---Operations---", "error-handling-client", "error-handling-server", - "---Curated References---", - "quick-reference", - "field-type-gallery", - "field-type-decision-tree", - "field-validation-rules", - "query-cheat-sheet", - "error-catalog", - "wire-format", - "protocol-diagram", - "permissions-matrix", - "backward-compatibility", - "contracts" + "standards", + "troubleshooting", + "---", + "contracts", + "cheatsheets" ] } diff --git a/content/docs/guides/plugin-development.mdx b/content/docs/guides/plugin-development.mdx index e87198e8f..2423fbecb 100644 --- a/content/docs/guides/plugin-development.mdx +++ b/content/docs/guides/plugin-development.mdx @@ -449,5 +449,5 @@ Metadata viewers declare which modes they support: ## Next Steps - [Common Patterns](/guides/common-patterns) — See how plugins fit into the application architecture -- [Error Catalog](/references/api/error-catalog) — Return proper error codes from your plugin -- [Field Type Gallery](/references/data/field-type-gallery) — Define custom objects with the right field types +- [Error Catalog](/docs/guides/cheatsheets/error-catalog) — Return proper error codes from your plugin +- [Field Type Gallery](/docs/guides/cheatsheets/field-type-gallery) — Define custom objects with the right field types diff --git a/content/docs/guides/troubleshooting.mdx b/content/docs/guides/troubleshooting.mdx index 471370006..f80f5e552 100644 --- a/content/docs/guides/troubleshooting.mdx +++ b/content/docs/guides/troubleshooting.mdx @@ -17,7 +17,7 @@ Solutions to the most common issues encountered when working with ObjectStack. **Cause:** The `type` value has a typo or uses an unsupported type name. -**Fix:** Use exact type names from the [Field Type Gallery](/references/data/field-type-gallery). Common mistakes: +**Fix:** Use exact type names from the [Field Type Gallery](/docs/guides/cheatsheets/field-type-gallery). Common mistakes: | ❌ Wrong | ✅ Correct | |:---|:---| diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 2f719fba6..7010522d5 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -3,24 +3,22 @@ title: ObjectStack Protocol description: The Metadata-Driven Protocol for the Post-SaaS Era. --- -import { Book, Compass, FileText, Layers, Database, Layout, Cpu, Code2, Bot, Workflow, Shield, Globe, Rocket, Terminal, FolderOpen } from 'lucide-react'; +import { Rocket, BookOpen, FileCode, Layers, Database, Layout, Cpu, Bot, Workflow, Shield, Globe, Terminal, FolderOpen, Lightbulb, Wrench, BookMarked } from 'lucide-react'; -**ObjectStack** is a **Metadata-Driven Protocol** for building enterprise architecture. -It standardizes how we define Data, UI, Automation, and AI Agents as structured JSON/YAML, decoupling *Business Intent* from *Technical Execution*. - -This documentation is the authoritative specification for the ObjectStack ecosystem. - -## Quick Start +**ObjectStack** is a **Metadata-Driven Protocol** for building enterprise applications. +Define Data, UI, Automation, and AI as structured metadata — ObjectStack handles the rest. ```bash -npx @objectstack/cli init my-app # Scaffold a project -cd my-app -os studio # Launch dev server + Console UI +npx @objectstack/cli init my-app && cd my-app && os studio ``` -Open [http://localhost:3000/_studio/](http://localhost:3000/_studio/) to browse your objects, test the API, and inspect metadata. +Open [http://localhost:3000/_studio/](http://localhost:3000/_studio/) to browse objects, test APIs, and inspect metadata. + +--- + +## Learn -## Getting Started +New to ObjectStack? Start here. } - title="Example Apps" - href="/docs/getting-started/examples" - description="Run the built-in Todo, CRM, and BI examples to learn hands-on." + icon={} + title="Core Concepts" + href="/docs/getting-started/core-concepts" + description="Metadata-driven development, design principles, and naming conventions." /> } - title="CLI Reference" - href="/docs/getting-started/cli" - description="All CLI commands: init, generate, serve, studio, compile, validate, and more." + icon={} + title="Architecture" + href="/docs/getting-started/architecture" + description="The three-layer protocol stack: ObjectQL, ObjectOS, ObjectUI." /> } - title="What is ObjectStack?" - href="/docs/getting-started" - description="Understand the philosophy: 'Intent over Implementation' and Metadata-Driven Architecture." + icon={} + title="Example Apps" + href="/docs/getting-started/examples" + description="Run the Todo, CRM, and BI examples to learn hands-on." /> -## Protocol Reference +## Build -The specification is divided into core domains. Each domain defines a set of Zod schemas that validate the metadata. - -### Core Pillars +Task-oriented guides for building real applications. } - title="Data Protocol" - href="/docs/references/data" - description="The schema for Objects, Fields, Queries, and Drivers." + title="Data Modeling" + href="/docs/guides/data-modeling" + description="Design objects, fields, relationships, and validation rules." /> } - title="UI Protocol" - href="/docs/references/ui" - description="The schema for Views, Forms, Dashboards, and Layouts." + icon={} + title="Business Logic" + href="/docs/guides/business-logic" + description="Workflows, approval flows, triggers, and formulas." /> } - title="Automation Protocol" - href="/docs/references/automation" - description="Flows, Workflows, Triggers, and Events." + icon={} + title="Security" + href="/docs/guides/security" + description="Profiles, permissions, sharing rules, and row-level security." /> } - title="AI Protocol" - href="/docs/references/ai" - description="Agents, RAG Pipelines, Models, and Prompts." + title="AI Capabilities" + href="/docs/guides/ai-capabilities" + description="AI agents, RAG pipelines, and natural language queries." + /> + } + title="Plugin Development" + href="/docs/guides/plugin-development" + description="Build, test, and publish custom plugins." + /> + } + title="API & Client SDK" + href="/docs/guides/api-reference" + description="REST, GraphQL, WebSocket APIs, and frontend integration." /> -### System & Infrastructure +## Understand + +Deep protocol specifications for implementers and architects. + } + title="ObjectQL — Data" + href="/docs/protocol/objectql" + description="Schema, state machines, query syntax, and security." + /> + } + title="ObjectUI — Interface" + href="/docs/protocol/objectui" + description="Layout DSL, widget contracts, and actions." + /> } - title="Kernel" - href="/docs/references/kernel" - description="Plugin Lifecycle, Manifests, Capabilities, and Loading." + title="ObjectOS — System" + href="/docs/protocol/objectos" + description="Lifecycle, HTTP/realtime, plugins, and config." /> + + +## Look Up + +Auto-generated schema reference and quick-lookup cheatsheets. + + } - title="System" - href="/docs/references/system" - description="Configuration, Logging, Jobs, and Caching." + icon={} + title="Schema Reference" + href="/docs/references" + description="Auto-generated docs for every Zod schema in the protocol." /> } - title="API & Identity" - href="/docs/references/api" - description="REST/GraphQL Contracts, Auth, and Identity Management." + icon={} + title="Cheatsheets" + href="/docs/guides/cheatsheets" + description="Field types, query syntax, error codes, and permissions at a glance." /> } - title="Integration" - href="/docs/references/integration" - description="Connectors, Webhooks, and External Data Sources." + icon={} + title="CLI Reference" + href="/docs/getting-started/cli" + description="All commands: init, generate, serve, studio, compile, validate." + /> + } + title="Glossary" + href="/docs/getting-started/glossary" + description="Key terminology across all 11 protocol namespaces." /> -## Why ObjectStack? +--- + +## Who is this for? -| Module | Responsibility | +| Audience | Use Case | | :--- | :--- | -| **[Data](/docs/references/data)** | Defines the shape of data (`Object`, `Field`) and how to access it. Agnostic to SQL/NoSQL. | -| **[UI](/docs/references/ui)** | The Projection. Defines User Interfaces as abstract JSON layouts (Views, Forms). | -| **[Automation](/docs/references/automation)** | The Logic. Orchestrates processes across the system. | -| **[AI](/docs/references/ai)** | The Intelligence. Defines Agents and knowledge retrieval strategies. | -| **[Kernel](/docs/references/kernel)** | The Runtime. Manages the lifecycle of all other protocols. | - -## For whom is this? - -* **Platform Architects:** Who want to build internal developer platforms (IDP) that scale. -* **Protocol Implementers:** Who want to write a new Driver for ObjectQL (e.g., for FoundationDB) or a new Renderer for ObjectUI (e.g., for Flutter). -* **AI Agent Developers:** Who need a deterministic, structured generic language for AI to generate software. -* **Low-Code Builders:** Who want a powerful metadata-driven platform for rapid application development. +| **Platform Architects** | Build internal developer platforms (IDP) that scale | +| **Protocol Implementers** | Write new Drivers for ObjectQL or Renderers for ObjectUI | +| **AI Agent Developers** | Use a structured, deterministic language for AI-generated software | +| **Low-Code Builders** | Rapid application development with metadata-driven workflows | diff --git a/content/docs/meta.json b/content/docs/meta.json index 36d16436a..d2cd0c4e9 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -4,7 +4,6 @@ "getting-started", "guides", "---", - "concepts", "protocol", "---", "references" diff --git a/content/docs/references/index.mdx b/content/docs/references/index.mdx index 1ac60e55d..cb583ed7b 100644 --- a/content/docs/references/index.mdx +++ b/content/docs/references/index.mdx @@ -401,14 +401,14 @@ const result = ObjectSchema.safeParse(objectDefinition);