Skip to content

design-principles.mdx

Latest commit

 

History

History
161 lines (107 loc) · 5.36 KB

design-principles.mdx

File metadata and controls

161 lines (107 loc) · 5.36 KB
Raw
title Design Principles
description The unshakable core principles that govern the ObjectStack ecosystem - The Constitution of the Post-SaaS Era

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

Design Principles

ObjectStack exists to return enterprise application development to its essence: Data.

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. Local-First by Default" description="The Cloud is a sync peer, not a master." />

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. allowRead: string (A slot for a formula)
App (Policy) Defines the business logic. allowRead: "$user.role == 'admin'"
Engine (Execution) Enforces the logic. Compiles formula to SQL WHERE clause.

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.

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

Principle IV: Local-First by Default

"The Cloud is a sync peer, not a master."

We reject the notion that software must stop working when the internet connection drops.

  • Latency is the enemy: All interactions should be optimistic and instant (0ms).
  • Ownership is the goal: The user's data essentially lives on their device. The server is just a hub for backup and collaboration.

The "Seven Hops" Problem

In a traditional Cloud app, a simple button click travels through:

Click → Wi-Fi → ISP → Cloud Load Balancer → Web Server → Database → Query Execution

...and then all the way back.

The Local-First Solution

ObjectStack apps are designed to read and write to a Local Database (embedded within the client environment) first.

Click → Local DB → UI Update (0ms Latency)

The synchronization with the cloud happens in the background, asynchronously.

Benefits:

  1. Instant Response: The UI reacts immediately (optimistic UI)
  2. Offline Capability: Field workers, airplanes, or spotty connections are no longer blockers
  3. Data Sovereignty: The data physically resides on the user's device

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.
Local-First Users own their data. The cloud is just for sync.

By adhering to these values, we build software that is resilient to change, respectful of user time, and technically sovereign.

Next Steps