Skip to content

Commit 9478e05

Browse files
Copilothotlong
Copilot
and
hotlong
committed
docs: create ObjectOS (System Protocol) documentation structure
- Add comprehensive ObjectOS overview explaining runtime orchestration - Document system lifecycle (boot, install, upgrade, rollback) - Create plugin package specification with manifest examples - Define configuration resolution with hierarchical merge strategies - Establish i18n standard with translation bundles and locale resolution Each page 200-400+ lines with practical examples, code snippets, and cross-references to ObjectQL/ObjectUI. Follows same tone and structure as existing protocol docs. Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent 58b311e commit 9478e05

31 files changed

Lines changed: 14944 additions & 0 deletions

‎content/docs/00-introduction/architecture.mdx‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
---
2+
title: Architecture
3+
description: Understanding the ObjectStack Protocol Architecture - How 11 protocol namespaces collaborate to build the Enterprise Kernel
4+
---
5+
6+
import { Layers, Database, Layout, ShieldCheck, Lock, Cog, Brain, Cloud, Zap } from 'lucide-react';
7+
8+
# Architecture Overview
9+
10+
ObjectStack is not a monolithic framework. It is a composable ecosystem designed around a **Protocol-Driven Architecture**. The system is organized into **11 protocol namespaces**, each responsible for a specific domain.
11+
12+
Each protocol is decoupled and communicates via standard JSON schemas defined with Zod. This allows you to swap out implementations (e.g., swapping the Postgres driver for MongoDB, or the React renderer for Flutter) without breaking the rest of the stack.
13+
14+
## The 11 Protocol Namespaces
15+
16+
ObjectStack is organized into 11 protocol namespaces:
17+
18+
<Cards>
19+
<Card
20+
icon={<Database />}
21+
title="Data Protocol"
22+
description="Object schema, fields, validation, and queries."
23+
/>
24+
<Card
25+
icon={<Cog />}
26+
title="Driver Protocol"
27+
description="Database adapters (Postgres, MongoDB, SQLite, etc.)."
28+
/>
29+
<Card
30+
icon={<ShieldCheck />}
31+
title="Permission Protocol"
32+
description="Object-level, field-level, sharing, and territory rules."
33+
/>
34+
<Card
35+
icon={<Layout />}
36+
title="UI Protocol"
37+
description="Apps, views, dashboards, reports, and themes."
38+
/>
39+
<Card
40+
icon={<Layers />}
41+
title="System Protocol"
42+
description="Events, jobs, translations, and audit logging."
43+
/>
44+
<Card
45+
icon={<Lock />}
46+
title="Auth Protocol"
47+
description="Identity, roles, sessions, and authentication strategies."
48+
/>
49+
<Card
50+
icon={<Cog />}
51+
title="Kernel Protocol"
52+
description="Plugin lifecycle, manifest, logging, and context."
53+
/>
54+
<Card
55+
icon={<Cloud />}
56+
title="Hub Protocol"
57+
description="Marketplace, licensing, tenancy, and deployment."
58+
/>
59+
<Card
60+
icon={<Brain />}
61+
title="AI Protocol"
62+
description="Agents, RAG, NLQ, predictive models, and orchestration."
63+
/>
64+
<Card
65+
icon={<Zap />}
66+
title="API Protocol"
67+
description="REST contracts, discovery, realtime, and routing."
68+
/>
69+
<Card
70+
icon={<Zap />}
71+
title="Automation Protocol"
72+
description="Workflows, flows, and webhooks."
73+
/>
74+
</Cards>
75+
76+
## The Three-Layer Architecture
77+
78+
While ObjectStack has 11 protocol namespaces, they are logically grouped into three architectural layers:
79+
80+
### 1. Data Layer (ObjectQL)
81+
**"The Universal Data Protocol"**
82+
83+
The foundation layer responsible for **Data Definition** and **Data Access**.
84+
85+
**Protocols:**
86+
- **Data Protocol:** Object schema, fields, validation, queries, filters
87+
- **Driver Protocol:** Database adapters for Postgres, MongoDB, SQLite, etc.
88+
- **Permission Protocol:** Object-level CRUD, field-level security, sharing rules
89+
- **AI Protocol:** AI agents, RAG pipelines, NLQ, predictive models
90+
91+
**Role:** Defines *Structure* (Schema) and *Intent* (Query AST).
92+
93+
**Responsibility:** It knows *what* a "Customer" object looks like, but it doesn't know *who* is accessing it or *how* it is displayed.
94+
95+
**Key Component:** The **Compiler**. It takes an abstract query (`find customers where active = true`) and translates it into optimized SQL/NoSQL queries for the specific underlying database.
96+
97+
### 2. Presentation Layer (ObjectUI)
98+
**"Server-Driven UI"**
99+
100+
The interface layer responsible for **Visual Representation** and **User Interaction**.
101+
102+
**Protocols:**
103+
- **UI Protocol:** Apps, views, dashboards, reports, actions, themes
104+
105+
**Role:** Projects the Data Protocol into visual components.
106+
107+
**Responsibility:** It knows *how* to display a "Customer" form, but it doesn't know the business rules or who can access it.
108+
109+
**Key Component:** The **Renderer**. It takes UI metadata (JSON) and renders it as native components (React, Flutter, etc.).
110+
111+
### 3. Control Layer (ObjectOS)
112+
**"The Business Kernel"**
113+
114+
The orchestration layer responsible for **Runtime** and **Governance**.
115+
116+
**Protocols:**
117+
- **System Protocol:** Events, jobs, translations, audit logging
118+
- **Auth Protocol:** Identity, roles, sessions, authentication
119+
- **Kernel Protocol:** Plugin lifecycle, manifest, context
120+
- **Hub Protocol:** Marketplace, licensing, tenancy
121+
- **API Protocol:** REST contracts, discovery, realtime
122+
- **Automation Protocol:** Workflows, flows, webhooks
123+
124+
**Role:** Orchestrates the entire system and enforces policies.
125+
126+
**Responsibility:** It knows *who* is accessing *what* and *when* actions should happen.
127+
128+
**Key Component:** The **Kernel**. It manages plugins, handles events, enforces security, and coordinates between layers.
129+
130+
## How They Work Together
131+
132+
```
133+
┌─────────────────────────────────────────┐
134+
│ Control Layer (ObjectOS) │
135+
│ ┌──────────┐ ┌────────┐ ┌──────────┐│
136+
│ │ Kernel │ │ Auth │ │ System ││
137+
│ │ Protocol │ │Protocol│ │ Protocol ││
138+
│ └──────────┘ └────────┘ └──────────┘│
139+
└─────────────────────────────────────────┘
140+
↕ ↕
141+
┌──────────────────┐ ┌──────────────────┐
142+
│ Data Layer (QL) │ │ UI Layer (UI) │
143+
│ ┌────────────┐ │ │ ┌────────────┐ │
144+
│ │ Data │ │ │ │ UI │ │
145+
│ │ Protocol │ │ │ │ Protocol │ │
146+
│ └────────────┘ │ │ └────────────┘ │
147+
│ ┌────────────┐ │ │ │
148+
│ │ Driver │ │ │ │
149+
│ │ Protocol │ │ │ │
150+
│ └────────────┘ │ │ │
151+
└──────────────────┘ └──────────────────┘
152+
↕
153+
┌──────────┐
154+
│ Database │
155+
└──────────┘
156+
```
157+
158+
### Example: Creating a Record
159+
160+
1. **UI Layer:** User clicks "Save" on a Customer form
161+
2. **Control Layer:** Kernel receives the request, validates authentication
162+
3. **Data Layer:** ObjectQL compiler generates SQL INSERT statement
163+
4. **Driver:** PostgreSQL driver executes the query
164+
5. **Control Layer:** Event system triggers "after_create" workflow
165+
6. **UI Layer:** Renderer updates the interface with the new record
166+
167+
## Protocol vs Implementation
168+
169+
**Critical Distinction:**
170+
171+
- **Protocol Layer:** Defined in `packages/spec` (This Repository)
172+
- Pure Zod schemas
173+
- TypeScript types
174+
- No runtime logic
175+
176+
- **Runtime Layer:** Implemented in separate packages
177+
- Node.js Kernel (`@objectstack/kernel`)
178+
- React Renderer (`@objectstack/react`)
179+
- PostgreSQL Driver (`@objectstack/driver-postgres`)
180+
181+
The protocol defines the "what" and "how." The runtime implements it.
182+
183+
## Design Benefits
184+
185+
### 1. Composability
186+
Each protocol can be used independently or combined with others.
187+
188+
### 2. Replaceability
189+
Don't like the React renderer? Build a Vue or Flutter one. The protocol stays the same.
190+
191+
### 3. Testability
192+
Test against the protocol specification, not a specific implementation.
193+
194+
### 4. Future-Proof
195+
New features are additive, not breaking. Implementations can evolve independently.
196+
197+
## Next Steps
198+
199+
- [Glossary](/docs/00-introduction/glossary) - Key terminology explained
200+
- [Core Concepts](/docs/01-core-concepts) - Understand metadata-driven development
201+
- [Protocols](/docs/02-protocols) - Dive into each protocol specification

‎content/docs/00-introduction/design-principles.mdx‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
title: Design Principles
3+
description: The unshakable core principles that govern the ObjectStack ecosystem - The Constitution of the Post-SaaS Era
4+
---
5+
6+
import { Scale, Code2, Database, ScrollText } from 'lucide-react';
7+
8+
# Design Principles
9+
10+
ObjectStack exists to return enterprise application development to its essence: **Data**.
11+
12+
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.
13+
14+
<Cards>
15+
<Card
16+
icon={<Scale />}
17+
title="I. Protocol Neutrality"
18+
description="The Protocol is law. The Implementation is merely an opinion."
19+
/>
20+
<Card
21+
icon={<Code2 />}
22+
title="II. Mechanism over Policy"
23+
description="Provide the tools to build rules, do not hardcode the rules themselves."
24+
/>
25+
<Card
26+
icon={<Database />}
27+
title="III. Single Source of Truth"
28+
description="There is no 'Code'. There is only Schema."
29+
/>
30+
<Card
31+
icon={<ScrollText />}
32+
title="IV. Local-First by Default"
33+
description="The Cloud is a sync peer, not a master."
34+
/>
35+
</Cards>
36+
37+
---
38+
39+
## Principle I: Protocol Neutrality
40+
41+
**"The Protocol is neutral. The Engine is replaceable."**
42+
43+
ObjectQL must not contain any logic specific to a particular language (e.g., Node.js), database (e.g., PostgreSQL), or runtime (e.g., Browser).
44+
45+
### The Law
46+
47+
- **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.
48+
- **Zero Leakage:** Implementation details (like React Hooks usage, or SQL specific syntax) must never leak into the Protocol definition.
49+
50+
### The Benefit
51+
52+
This ensures that an ObjectStack application defined today can theoretically run on:
53+
54+
- A Node.js server with PostgreSQL (Today's Standard)
55+
- A Python server with SQLite (AI/Data Science)
56+
- A Rust WASM module in the browser (Local-First)
57+
58+
---
59+
60+
## Principle II: Mechanism over Policy
61+
62+
**"Give them the physics, not the simulation."**
63+
64+
ObjectStack provides the **Mechanisms** (The "How"):
65+
66+
- *"Here is how you define a validation rule."*
67+
- *"Here is how you define a permission scope."*
68+
69+
ObjectStack never dictates the **Policy** (The "What"):
70+
71+
- *It never says "Passwords must be 8 characters".*
72+
- *It never says "Users must belong to a Department".*
73+
74+
### Separation of Concerns
75+
76+
We cleanly separate the **Definition** from the **Execution**.
77+
78+
| Layer | Responsibility | Example |
79+
| :--- | :--- | :--- |
80+
| **Protocol (Mechanism)** | Defines the capabilities. | `allowRead: string` (A slot for a formula) |
81+
| **App (Policy)** | Defines the business logic. | `allowRead: "$user.role == 'admin'"` |
82+
| **Engine (Execution)** | Enforces the logic. | Compiles formula to SQL `WHERE` clause. |
83+
84+
---
85+
86+
## Principle III: The Single Source of Truth
87+
88+
**"There is no 'Code'. There is only Schema."**
89+
90+
In a traditional application, the "truth" is scattered:
91+
92+
1. Database Schema (`table.sql`)
93+
2. Backend Models (`User.ts`)
94+
3. Frontend Validation (`schema.zod.ts`)
95+
4. API Documentation (`swagger.json`)
96+
97+
In ObjectStack, **The Object Protocol is the only truth.**
98+
99+
- The Database is a *derivative* of the Protocol.
100+
- The UI is a *projection* of the Protocol.
101+
- The API is a *consequence* of the Protocol.
102+
103+
If you change the Protocol, the entire system (DB, API, UI) must adapt automatically.
104+
105+
---
106+
107+
## Principle IV: Local-First by Default
108+
109+
**"The Cloud is a sync peer, not a master."**
110+
111+
We reject the notion that software must stop working when the internet connection drops.
112+
113+
- **Latency is the enemy:** All interactions should be optimistic and instant (0ms).
114+
- **Ownership is the goal:** The user's data essentially lives on their device. The server is just a hub for backup and collaboration.
115+
116+
### The "Seven Hops" Problem
117+
118+
In a traditional Cloud app, a simple button click travels through:
119+
120+
```
121+
Click → Wi-Fi → ISP → Cloud Load Balancer → Web Server → Database → Query Execution
122+
```
123+
124+
...and then all the way back.
125+
126+
### The Local-First Solution
127+
128+
ObjectStack apps are designed to read and write to a **Local Database** (embedded within the client environment) first.
129+
130+
```
131+
Click → Local DB → UI Update (0ms Latency)
132+
```
133+
134+
The synchronization with the cloud happens in the background, asynchronously.
135+
136+
**Benefits:**
137+
138+
1. **Instant Response:** The UI reacts immediately (optimistic UI)
139+
2. **Offline Capability:** Field workers, airplanes, or spotty connections are no longer blockers
140+
3. **Data Sovereignty:** The data physically resides on the user's device
141+
142+
---
143+
144+
## Summary
145+
146+
These principles guide every design decision in ObjectStack:
147+
148+
| Principle | What it Means |
149+
| :--- | :--- |
150+
| **Protocol Neutrality** | The spec is separate from implementation. ObjectStack can run anywhere. |
151+
| **Mechanism over Policy** | We provide the tools, you define the rules. |
152+
| **Single Source of Truth** | The schema is the application. Everything else derives from it. |
153+
| **Local-First** | Users own their data. The cloud is just for sync. |
154+
155+
By adhering to these values, we build software that is **resilient to change**, **respectful of user time**, and **technically sovereign**.
156+
157+
## Next Steps
158+
159+
- [Architecture](/docs/00-introduction/architecture) - See how these principles shape the system
160+
- [Glossary](/docs/00-introduction/glossary) - Understand key terms
161+
- [Core Concepts](/docs/01-core-concepts) - Learn about metadata-driven development

0 commit comments

Comments
 (0)