Skip to content

Commit f4d8ee7

Browse files
hotlonghotlong
committed
Add core values, enterprise patterns, and terminology docs
Introduced three new documentation pages: Core Values, Enterprise Patterns, and Terminology. These pages outline ObjectStack's foundational principles, approaches to complex enterprise logic, and a glossary of key terms used throughout the ecosystem.
1 parent 49485ba commit f4d8ee7

File tree

3 files changed

+351
-0
lines changed

3 files changed

+351
-0
lines changed

‎content/docs/concepts/core-values.mdx‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: Core Values
3+
description: "Deep dive into the three pillars of ObjectStack: Protocol-Driven Architecture, Local-First Data Sovereignty, and Database Agnosticism."
4+
sidebar_position: 2
5+
slug: /concepts/core-values
6+
---
7+
8+
# Core Values
9+
10+
ObjectStack is built upon three non-negotiable architectural values. These are not just "features"; they are the constraints that guide every design decision we make.
11+
12+
## 1. Protocol-Driven: Intent over Implementation
13+
14+
The fundamental thesis of ObjectStack is that **application logic should be defined by declarative data, not imperative code.**
15+
16+
### The Problem with "Code-First"
17+
In modern development, the "Intent" (e.g., *“This field is a required email address”*) is often scattered across three layers:
18+
1. **Database:** SQL constraints (`NOT NULL`).
19+
2. **Backend:** ORM validation (e.g., TypeORM decorators).
20+
3. **Frontend:** UI validation (e.g., React Hook Form + Zod).
21+
22+
When the business requirement changes, you must update code in three places. This is **Implementation Coupling**.
23+
24+
### The Protocol-Driven Solution
25+
ObjectStack centralizes the "Intent" into a single Protocol Definition (JSON/YAML). The implementation layers (React, Node.js, SQL) act merely as **Runtime Engines** that interpret this protocol.
26+
27+
28+
29+
* **The UI is a Projection:** ObjectUI does not "build" a form; it *projects* the ObjectQL schema into a visual representation.
30+
* **The API is a Consequence:** You do not write endpoints; ObjectOS *generates* the secure graph based on the access control protocol.
31+
32+
> **Analogy:** Think of ObjectStack as a Web Browser. You send it HTML (Protocol), and it renders a page. You don't rewrite the browser engine (C++) every time you want to change the text on a website.
33+
34+
## 2. Local-First: Ownership & Zero Latency
35+
36+
For the past decade, "Cloud-Native" has been the gold standard. While it solved deployment issues, it introduced a new problem: **The User rents their access to data.**
37+
38+
If the server is slow, the app is slow. If the internet is down, the app is dead.
39+
40+
### The "Seven Hops" Problem
41+
In a traditional Cloud app, a simple button click travels through:
42+
`Click -> Wi-Fi -> ISP -> Cloud Load Balancer -> Web Server -> Database -> Query Execution` ...and then all the way back.
43+
44+
### The Local-First Solution
45+
ObjectStack apps are designed to read and write to a **Local Database** (embedded within the client environment) first.
46+
`Click -> Local DB -> UI Update` (0ms Latency).
47+
48+
The synchronization with the cloud happens in the background, asynchronously.
49+
50+
1. **Instant Response:** The UI reacts immediately (optimistic UI), making enterprise apps feel as snappy as native desktop software.
51+
2. **Offline Capability:** Field workers, airplanes, or spotty connections are no longer blockers.
52+
3. **Data Sovereignty:** The data physically resides on the user's device. The cloud acts as a synchronization hub, not the sole gatekeeper.
53+
54+
## 3. Database Agnostic: The "Universal Compiler"
55+
56+
Vendor lock-in is the enemy of longevity. A business application usually outlives the database technology it was originally built on.
57+
58+
ObjectQL treats the underlying database as an **Implementation Detail**.
59+
60+
### The Compiler Approach
61+
Instead of being a runtime wrapper (like an ORM), ObjectQL functions as a **Compiler**.
62+
1. **Input:** ObjectQL Abstract Syntax Tree (AST).
63+
2. **Process:** Compile AST into dialect-specific SQL.
64+
3. **Output:** Highly optimized queries for the target target.
65+
66+
This architecture allows for radical flexibility:
67+
* **Dev:** Run on **SQLite** (Zero setup, single file).
68+
* **Prod:** Run on **PostgreSQL** (Robust, scalable).
69+
* **Edge:** Run on **Cloudflare D1** (Distributed).
70+
* **Legacy:** Connect to an existing **Oracle/SQL Server** (Integration).
71+
72+
You change the *Driver*, not the *Code*.
73+
74+
## Summary
75+
76+
| Value | The Old Way | The ObjectStack Way |
77+
| :--- | :--- | :--- |
78+
| **Architecture** | Code-Driven (Imperative) | Protocol-Driven (Declarative) |
79+
| **Logic Location** | Scattered (DB + API + UI) | Centralized (JSON/YAML Schema) |
80+
| **Data Access** | Cloud-Dependent (Online Only) | Local-First (Offline + Sync) |
81+
| **Storage** | Locked to Vendor | Database Agnostic |
82+
83+
By adhering to these values, we build software that is **resilient to change**, **respectful of user time**, and **technically sovereign**.

‎content/docs/concepts/enterprise-patterns.mdx‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
title: Enterprise Patterns
3+
description: Handling complex ERP/CRM business logic (State Machines, Calculations, RBAC) using the Protocol-Driven approach.
4+
sidebar_position: 4
5+
slug: /concepts/enterprise-patterns
6+
---
7+
8+
# Enterprise Patterns
9+
10+
A common misconception about "Low-Code" or "Protocol-Driven" platforms is that they are only suitable for simple CRUD applications.
11+
12+
While true for many visual builders, **ObjectStack** is architected specifically for the complexity of Enterprise Resource Planning (ERP) and Customer Relationship Management (CRM) systems. We handle complexity not by hiding it, but by **modeling it** explicitly in the protocol.
13+
14+
Here is how we map common Enterprise Patterns to the ObjectStack architecture.
15+
16+
## 1. Workflows as State Machines (FSM)
17+
18+
In enterprise software, a record (e.g., a "Purchase Order") is rarely just static data. It is a living entity that moves through a lifecycle.
19+
20+
**The Anti-Pattern:**
21+
Writing scattered `if/else` logic in controllers:
22+
```javascript
23+
// Don't do this
24+
if (order.status === 'draft' && user.role === 'manager') {
25+
order.status = 'approved';
26+
}
27+
28+
```
29+
30+
**The ObjectStack Pattern:**
31+
We define the lifecycle as a **Finite State Machine (FSM)** in the ObjectOS Protocol. This makes the business process deterministic and visualizeable.
32+
33+
```yaml
34+
# workflows/purchase_order.yaml
35+
name: purchase_approval
36+
object: purchase_order
37+
states:
38+
draft:
39+
initial: true
40+
on_exit: ['validate_budget']
41+
transitions:
42+
submit: pending_approval
43+
pending_approval:
44+
transitions:
45+
approve: approved
46+
reject: rejected
47+
guards:
48+
approve: "user.has_permission('approve_budget')"
49+
approved:
50+
final: true
51+
52+
```
53+
54+
* **Deterministic:** An order *cannot* jump from `draft` to `shipped` unless the protocol allows it.
55+
* **Audit:** The engine automatically logs every transition (Who moved it? When? Why?).
56+
57+
## 2. High-Precision Calculations (Virtual Columns)
58+
59+
ERPs are essentially databases mixed with complex spreadsheets. You need to calculate tax, aggregate line items, and compute margins—often across millions of rows.
60+
61+
**The Anti-Pattern:**
62+
Fetching all data into Node.js memory to loop and calculate. This kills performance.
63+
64+
**The ObjectStack Pattern:**
65+
We use **ObjectQL Virtual Columns** to compile logic down to the database layer.
66+
67+
```yaml
68+
# objects/invoice.object.yaml
69+
name: invoice
70+
fields:
71+
lines:
72+
type: master_detail
73+
reference_to: invoice_line
74+
75+
# A summary field that compiles to a SQL subquery or aggregation
76+
total_amount:
77+
type: summary
78+
reference_to: lines
79+
summary_type: sum
80+
summary_field: amount
81+
82+
# A formula field that compiles to a SQL expression
83+
margin_percent:
84+
type: formula
85+
formula: "(${total_amount} - ${cost}) / ${total_amount}"
86+
precision: 18
87+
scale: 2
88+
89+
```
90+
91+
* **Performance:** The ObjectQL Compiler translates `total_amount` into a highly optimized SQL `SUM()` or a materialized view.
92+
* **Consistency:** The calculation is defined once in the Schema, ensuring the API, the UI, and the Reports all show the exact same number.
93+
94+
## 3. Granular Governance (Field-Level Security)
95+
96+
In an HR system, everyone can see an "Employee" record, but only HR Managers can see the "Salary" field.
97+
98+
**The Anti-Pattern:**
99+
Manually stripping fields in API controllers: `delete user.salary`. This is error-prone; developers often forget one endpoint (e.g., the search API).
100+
101+
**The ObjectStack Pattern:**
102+
Security is injected into the **Compilation Phase**.
103+
104+
```yaml
105+
# permissions/hr_manager.permission.yaml
106+
role: hr_manager
107+
object: employee
108+
allow_read: true
109+
allow_edit: true
110+
field_permissions:
111+
salary:
112+
read: true
113+
edit: true
114+
115+
# permissions/employee.permission.yaml
116+
role: employee
117+
object: employee
118+
allow_read: true
119+
field_permissions:
120+
salary:
121+
read: false # The compiler physically removes this column from the SELECT statement
122+
123+
```
124+
125+
* **Safety:** If a user without permission tries to query `salary`, the ObjectQL engine throws a compilation error or returns `null` (depending on config). It never touches the database.
126+
127+
## 4. Master-Detail Interfaces (Compound UI)
128+
129+
Enterprise users require high-density interfaces. They need to edit an Order (Header) and its Items (Lines) on a single screen without page refreshes.
130+
131+
**The ObjectStack Pattern:**
132+
ObjectUI supports **Compound Layouts** defined via JSON.
133+
134+
```json
135+
{
136+
"type": "layout.master_detail",
137+
"props": {
138+
"master_object": "order",
139+
"detail_object": "order_line",
140+
"link_field": "order_id"
141+
},
142+
"children": [
143+
{
144+
"region": "header",
145+
"type": "form",
146+
"fields": ["customer", "date", "status"]
147+
},
148+
{
149+
"region": "body",
150+
"type": "grid.editable", // An Excel-like editable table
151+
"fields": ["product", "quantity", "price", "subtotal"]
152+
}
153+
]
154+
}
155+
156+
```
157+
158+
* **Transaction Awareness:** The ObjectUI engine knows these two datasets are linked. When the user clicks "Save", it constructs a **Transactional Mutation** to save both the Order and Lines atomically.
159+
160+
## 5. Audit Trails & Compliance
161+
162+
For Finance and Healthcare (HIPAA/SOX), "Who changed what" is a legal requirement.
163+
164+
**The ObjectStack Pattern:**
165+
Because all mutations go through the ObjectQL Protocol, auditing is enabled by a single flag.
166+
167+
* **Protocol:** The engine captures the `before` and `after` state of every field.
168+
* **Storage:** Changes are written to a localized `audit_log` table (or an immutable ledger).
169+
* **Visualization:** ObjectUI provides a built-in "History" component that renders this log instantly.
170+
171+
## Summary
172+
173+
ObjectStack handles enterprise complexity by **elevating patterns into protocols**.
174+
175+
| Complexity | Traditional Code | ObjectStack Protocol |
176+
| --- | --- | --- |
177+
| **Process** | `if/else` spaghetti | **Finite State Machines (YAML)** |
178+
| **Math** | Looping in memory | **Virtual Columns (SQL Compilation)** |
179+
| **Secrecy** | Manual API filtering | **Engine-Level RBAC** |
180+
| **UX** | Hardcoded React forms | **Master-Detail Layouts (JSON)** |
181+
| **History** | Custom logging logic | **Native Audit Trail** |

‎content/docs/concepts/terminology.mdx‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: Terminology
3+
description: A glossary of key terms, concepts, and jargon used within the ObjectStack ecosystem.
4+
sidebar_position: 5
5+
slug: /concepts/terminology
6+
---
7+
8+
# Terminology
9+
10+
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.
11+
12+
## The Ecosystem
13+
14+
### ObjectStack
15+
The umbrella term for the entire suite of protocols and reference implementations. It encompasses the Data Layer (ObjectQL), the UI Layer (ObjectUI), and the Operating System (ObjectOS).
16+
17+
### ObjectQL (The Data Protocol)
18+
A database-agnostic protocol for defining data structures and querying them. Unlike GraphQL (which is an API spec), ObjectQL is a **Database Compiler** that translates abstract intent into dialect-specific SQL (e.g., PostgreSQL, SQLite).
19+
20+
### ObjectUI (The View Protocol)
21+
A JSON-based specification for describing user interfaces. It follows the **Server-Driven UI (SDUI)** pattern, where the backend dictates the layout, hierarchy, and behavior, and the frontend (React/Flutter) acts as a renderer.
22+
23+
### ObjectOS (The Kernel)
24+
The runtime environment that orchestrates the ecosystem. It manages identity, plugin lifecycles, workflow execution, and data synchronization between client and server.
25+
26+
---
27+
28+
## Architecture Concepts
29+
30+
### Protocol-Driven
31+
A development paradigm where logic is defined in static, declarative data formats (JSON/YAML) rather than imperative code. The goal is to separate the **Intent** (Business Logic) from the **Implementation** (Tech Stack).
32+
33+
### Local-First
34+
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.
35+
36+
### Database Compiler
37+
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.
38+
39+
### Virtual Column
40+
A field defined in the ObjectQL schema that does not exist physically in the database table but is computed on the fly.
41+
* *Example:* A SQL subquery or expression injected into the `SELECT` statement at compile time.
42+
43+
---
44+
45+
## Data & Schema
46+
47+
### Object (Entity)
48+
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.
49+
50+
### Driver
51+
An adapter plugin that allows ObjectQL to talk to a specific underlying storage engine.
52+
* *Example:* `@objectql/driver-postgres`, `@objectql/driver-sqlite`.
53+
54+
### AST (Abstract Syntax Tree)
55+
The intermediate representation of a query or schema. ObjectQL parses a JSON request into an AST before the Compiler translates it into SQL. This allows for security injection and analysis before execution.
56+
57+
### Manifest
58+
The entry point configuration file (usually `package.json` or `manifest.json`) for an ObjectOS Plugin. It declares dependencies, creates resources, and registers extensions.
59+
60+
---
61+
62+
## Interface & Logic
63+
64+
### Layout
65+
A JSON structure defined in ObjectUI that describes the visual arrangement of components. Layouts can be nested and dynamic (e.g., Master-Detail, Grid, Kanban).
66+
67+
### Workflow
68+
A business process defined as a **Finite State Machine (FSM)**. It consists of States (e.g., `draft`, `approved`), Transitions, and Guards.
69+
70+
### Action
71+
A discrete unit of logic that can be triggered by a user (UI button) or a system event (Workflow transition). Actions are often defined in the schema and implemented in TypeScript.
72+
73+
### Component Registry
74+
A map within the ObjectUI Runtime that links a string identifier (e.g., `"chart.bar"`) to a real React Component. This allows the JSON protocol to instantiate UI elements dynamically.
75+
76+
---
77+
78+
## Governance
79+
80+
### Space (Workspace)
81+
A logical isolation unit for multi-tenancy. A single ObjectOS instance can host multiple Spaces. Data is physically segregated by a `space_id` column.
82+
83+
### FLS (Field-Level Security)
84+
A granular permission model where access control is applied to individual fields (columns), not just the whole object (row).
85+
86+
### TCK (Technology Compatibility Kit)
87+
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.

0 commit comments

Comments
 (0)