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.

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.

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:

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

Next Steps

• Architecture - See how these principles shape the system
• Glossary - Understand key terms
• Core Concepts - Learn about metadata-driven development