Skip to content

design-principles.mdx

Latest commit

 

History

History
163 lines (109 loc) · 6.19 KB

design-principles.mdx

File metadata and controls

163 lines (109 loc) · 6.19 KB
Raw
title Design Principles
description The unshakable core principles that govern ObjectStack as an AI-native business backend

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

Design Principles

ObjectStack exists to make enterprise application development explicit enough for both humans and AI agents to operate safely: structured business metadata.

To maintain a healthy, decoupled, and future-proof ecosystem, we uphold the following core principles. These are not suggestions; they are the constraints that enable our freedom.

} 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. Agent-Ready Boundaries" description="Agents may act only through typed, permission-aware, auditable surfaces." />

Principle I: Protocol Neutrality

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

ObjectQL must not contain any logic specific to a particular language (e.g., Node.js), database (e.g., PostgreSQL), or runtime (e.g., Browser).

The Law

  • Spec before Engine: Any feature must first be defined in the Specification layer (packages/spec) before a single line of code is written in the Engine layer. We reject the "implement first, standardize later" approach.
  • Zero Leakage: Implementation details (like React Hooks usage, or SQL specific syntax) must never leak into the Protocol definition.

The Benefit

This ensures that an ObjectStack application defined today can theoretically run on:

  • A Node.js server with PostgreSQL (Today's Standard)
  • A Python server with SQLite (AI/Data Science)
  • A Rust WASM module in the browser (Local-First)

Principle II: Mechanism over Policy

"Give them the physics, not the simulation."

ObjectStack provides the Mechanisms (The "How"):

  • "Here is how you define a validation rule."
  • "Here is how you define a permission scope."

ObjectStack never dictates the Policy (The "What"):

  • It never says "Passwords must be 8 characters".
  • It never says "Users must belong to a Department".

Separation of Concerns

We cleanly separate the Definition from the Execution.

Layer Responsibility Example
Protocol (Mechanism) Defines the capabilities. condition: Expression (a CEL predicate slot for sharing rules)
App (Policy) Defines the business logic. condition: P\record.department == "Sales"``
Engine (Execution) Enforces the logic. Compiles formula to SQL WHERE clause.

Policies are metadata, not code. Permission rules, validation predicates, sharing conditions, and flow guards are all expressed as analyzable CEL/Zod metadata — the same engine evaluates them for human users, REST callers, and AI agent tools, and every decision is traceable to a versioned artifact.

Principle III: The Single Source of Truth

"There is no 'Code'. There is only Schema."

In a traditional application, the "truth" is scattered:

  1. Database Schema (table.sql)
  2. Backend Models (User.ts)
  3. Frontend Validation (schema.zod.ts)
  4. API Documentation (swagger.json)

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.

If you change the Protocol, the entire system (DB, API, UI, tools, and audit context) must adapt automatically.

Principle IV: Agent-Ready Boundaries

"Agents are powerful only when their boundaries are explicit."

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.

  • Typed inputs: Tool schemas derive from object fields, action contracts, and validation rules.
  • Permission-aware execution: RBAC, RLS, and FLS apply to agent actions exactly as they apply to users.
  • Auditable outcomes: Every agent action should be traceable to the artifact version, user/org context, tool, input, and result.

The Hidden Tool Problem

In many AI-enabled apps, the agent sees a set of hand-written tools that drift from the real business system:

Database schema -> App code -> UI state -> Custom query -> Hand-written MCP tool

Each translation layer can lose validation, authorization, or business meaning.

The ObjectStack Solution

ObjectStack derives agent capabilities from the protocol itself:

Zod metadata -> Environment Artifact -> ObjectStack runtime -> API / UI / MCP tools

Benefits:

  1. No tool drift: Generated tools stay aligned with object schemas and permissions.
  2. Safer autonomy: Agents act inside explicit business boundaries.
  3. Auditability: Runtime decisions can be traced to versioned metadata.

Summary

These principles guide every design decision in ObjectStack:

Principle What it Means
Protocol Neutrality The spec is separate from implementation. ObjectStack can run anywhere.
Mechanism over Policy We provide the tools, you define the rules.
Single Source of Truth The schema is the application. Everything else derives from it.
Agent-Ready Boundaries Agents act through typed, permission-aware, auditable capabilities.

By adhering to these values, we build software that is resilient to change, safe for automation, and explicit enough for AI-native business execution.

Next Steps