Skip to content

Commit b151b28

Browse files
hotlonghotlong
authored
Merge pull request #651 from objectstack-ai/copilot/restructure-documentation-website
2 parents 2dd1322 + 785a346 commit b151b28

27 files changed

+1139
-157
lines changed

‎content/docs/getting-started/architecture.mdx‎

Lines changed: 639 additions & 0 deletions
Large diffs are not rendered by default.

‎content/docs/getting-started/core-concepts.mdx‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
title: Core Concepts
3+
description: The foundational ideas behind ObjectStack — metadata-driven development, protocol-first design, and the principles that shape every decision
4+
---
5+
6+
import { Scale, Code2, Database, ScrollText, Laptop } from 'lucide-react';
7+
8+
# Core Concepts
9+
10+
Before diving into code, understanding these foundational ideas will make everything else click.
11+
12+
## Metadata-Driven Development
13+
14+
Metadata-driven development is a paradigm shift where **application logic is defined by declarative data (metadata), not imperative code.**
15+
16+
### The Problem with Code-First
17+
18+
In traditional development, the "Intent" (e.g., *"This field is a required email address"*) is scattered across multiple layers:
19+
20+
1. **Database:** SQL constraints (`NOT NULL`, `CHECK`)
21+
2. **Backend:** ORM validation (TypeORM decorators, Prisma schemas)
22+
3. **Frontend:** UI validation (React Hook Form + Zod)
23+
4. **Documentation:** API specs (OpenAPI/Swagger)
24+
25+
When a business requirement changes, you must update code in **three or four places**. This is **Implementation Coupling**.
26+
27+
### The ObjectStack Way
28+
29+
ObjectStack centralizes the "Intent" into a **single Protocol Definition**:
30+
31+
```typescript
32+
// ONE definition — everything else derives from it
33+
import { defineStack } from '@objectstack/spec';
34+
35+
export default defineStack({
36+
objects: [{
37+
name: 'user',
38+
label: 'User',
39+
fields: [
40+
{ name: 'phone', label: 'Phone Number', type: 'phone', required: true },
41+
],
42+
}],
43+
});
44+
```
45+
46+
From this single definition, ObjectStack automatically:
47+
48+
✅ Generates database schema
49+
✅ Creates validation rules
50+
✅ Builds CRUD APIs
51+
✅ Renders form fields
52+
✅ Produces API documentation
53+
54+
### The Three Truths
55+
56+
1. **The UI is a Projection** — The form is generated from the schema, not hand-coded
57+
2. **The API is a Consequence** — REST/GraphQL endpoints appear automatically from object definitions
58+
3. **The Schema is the Application** — Your entire business logic lives in metadata files
59+
60+
### When to Use Metadata-Driven
61+
62+
✅ **Great for:** CRUD apps, SaaS platforms, admin panels, rapid prototyping, multi-tenant systems
63+
64+
❌ **Not ideal for:** Pixel-perfect custom UIs, real-time 3D/games, highly unique domains
65+
66+
---
67+
68+
## Design Principles
69+
70+
ObjectStack is governed by four unshakable principles:
71+
72+
<Cards>
73+
<Card
74+
icon={<Scale />}
75+
title="I. Protocol Neutrality"
76+
description="The Protocol is law. The Implementation is merely an opinion."
77+
/>
78+
<Card
79+
icon={<Code2 />}
80+
title="II. Mechanism over Policy"
81+
description="Provide the tools to build rules, do not hardcode the rules themselves."
82+
/>
83+
<Card
84+
icon={<Database />}
85+
title="III. Single Source of Truth"
86+
description="There is no 'Code'. There is only Schema."
87+
/>
88+
<Card
89+
icon={<ScrollText />}
90+
title="IV. Local-First by Default"
91+
description="The Cloud is a sync peer, not a master."
92+
/>
93+
</Cards>
94+
95+
### Protocol Neutrality
96+
97+
**"The Protocol is neutral. The Engine is replaceable."**
98+
99+
- **Spec before Engine:** Features must be defined in the Specification layer before any engine code is written
100+
- **Zero Leakage:** Implementation details (React, SQL, etc.) never leak into Protocol definitions
101+
102+
This ensures ObjectStack apps can run on Node.js + PostgreSQL today, Python + SQLite tomorrow, or Rust WASM in the browser.
103+
104+
### Mechanism over Policy
105+
106+
**"Give them the physics, not the simulation."**
107+
108+
| Layer | Responsibility | Example |
109+
| :--- | :--- | :--- |
110+
| **Protocol** | Defines capabilities | `allowRead: string` (a slot for a formula) |
111+
| **App** | Defines business logic | `allowRead: "$user.role == 'admin'"` |
112+
| **Engine** | Enforces the logic | Compiles formula to SQL `WHERE` clause |
113+
114+
### Single Source of Truth
115+
116+
In ObjectStack, **the Object Protocol is the only truth:**
117+
118+
- The Database is a *derivative* of the Protocol
119+
- The UI is a *projection* of the Protocol
120+
- The API is a *consequence* of the Protocol
121+
122+
Change the Protocol → the entire system adapts automatically.
123+
124+
### Local-First by Default
125+
126+
All interactions should be instant (0ms latency). The user's data lives on their device; the server is a sync hub.
127+
128+
```
129+
Traditional: Click → Wi-Fi → ISP → Cloud → DB → Response
130+
Local-First: Click → Local DB → UI Update (0ms)
131+
```
132+
133+
---
134+
135+
## Naming Conventions
136+
137+
ObjectStack enforces strict naming rules for consistency:
138+
139+
| Element | Convention | Examples |
140+
|---------|-----------|----------|
141+
| **Object names** (machine) | `snake_case` | `todo_task`, `user_profile` |
142+
| **Field names** (machine) | `snake_case` | `first_name`, `is_active` |
143+
| **Export names** (constants) | `PascalCase` | `TodoTask`, `UserProfile` |
144+
| **Config keys** (properties) | `camelCase` | `maxLength`, `defaultValue` |
145+
146+
## Summary
147+
148+
| Aspect | Traditional | Metadata-Driven |
149+
| :--- | :--- | :--- |
150+
| **Definition** | Code in multiple files | Single metadata definition |
151+
| **Changes** | Update 3-4 places | Update once |
152+
| **Type Safety** | Manual synchronization | Automatic from Zod |
153+
| **Flexibility** | Locked to tech stack | Technology agnostic |
154+
| **Boilerplate** | High (300+ lines) | Low (30 lines) |
155+
156+
## Next Steps
157+
158+
- [Architecture](/docs/getting-started/architecture) — How the protocol layers work together
159+
- [Quick Start](/docs/getting-started/quick-start) — Build your first app in 5 minutes
160+
- [Glossary](/docs/getting-started/glossary) — Key terminology

‎content/docs/getting-started/glossary.mdx‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: Glossary
3+
description: The Glossary of the ObjectStack Ecosystem. Speaking the same language.
4+
---
5+
6+
import { Book, Server, Code, Database } from 'lucide-react';
7+
8+
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.
9+
10+
## The Ecosystem
11+
12+
### ObjectStack
13+
The umbrella term for the entire suite of protocols and reference implementations. It is organized into **11 protocol namespaces** grouped into three architectural layers.
14+
15+
### Protocol Namespace
16+
A logical grouping of related schemas and types defined with Zod. ObjectStack has 11 protocol namespaces: Data, Driver, Permission, UI, System, Auth, Kernel, Hub, AI, API, and Automation.
17+
18+
---
19+
20+
## The 11 Protocol Namespaces
21+
22+
### Data Protocol
23+
Defines the core business data model. Includes Object schema, Field types, Validation rules, Query AST, and Filter conditions. This is the foundation of ObjectQL.
24+
25+
### Driver Protocol
26+
Database adapter interface for connecting to various storage engines (PostgreSQL, MongoDB, SQLite, Redis, etc.). Drivers implement a standard interface for CRUD operations and query execution.
27+
28+
### Permission Protocol
29+
Access control system including object-level permissions (CRUD), field-level security (FLS), sharing rules, and territory management. Determines who can see and modify what data.
30+
31+
### UI Protocol
32+
Server-Driven UI specification for building user interfaces. Includes App structure, Views (List/Form/Kanban/Calendar), Dashboards, Reports, Themes, and Actions.
33+
34+
### System Protocol
35+
Infrastructure services including Event Bus, Job Scheduling, Translation (i18n), and Audit Logging. Manages system-level concerns.
36+
37+
### Auth Protocol
38+
Identity and access management including User accounts, Sessions, Roles, Organization structure, and various authentication strategies (OAuth, SAML, LDAP, etc.).
39+
40+
### Kernel Protocol
41+
Plugin system and runtime management. Includes Plugin lifecycle, Manifest definition, Logger configuration, and Runtime Context. The core of ObjectOS.
42+
43+
### Hub Protocol
44+
SaaS and marketplace features including Multi-tenancy, Licensing, Marketplace plugins, and Deployment configurations. Enables commercial distribution.
45+
46+
### AI Protocol
47+
Artificial intelligence capabilities including AI Agents, RAG pipelines, Natural Language Query (NLQ), Predictive models, Cost tracking, and Orchestration.
48+
49+
### API Protocol
50+
External communication layer including REST contracts, API discovery, Realtime subscriptions (WebSocket/SSE), and Routing configuration.
51+
52+
### Automation Protocol
53+
Business process automation including Workflows (state machines), Flows (visual logic), and Webhooks (HTTP callbacks).
54+
55+
---
56+
57+
## Architecture Concepts
58+
59+
### Protocol-Driven
60+
A development paradigm where logic is defined in static, declarative data formats (JSON/YAML) with Zod schemas rather than imperative code. The goal is to separate the **Intent** (Business Logic) from the **Implementation** (Tech Stack).
61+
62+
### Local-First
63+
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.
64+
65+
### Database Compiler
66+
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.
67+
68+
### Virtual Field
69+
A field defined in the Data Protocol schema that does not exist physically in the database table but is computed on the fly.
70+
* *Example:* A SQL subquery or expression injected into the `SELECT` statement at compile time.
71+
72+
---
73+
74+
## Data & Schema
75+
76+
### Object (Entity)
77+
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.
78+
79+
### Driver
80+
An adapter plugin (Driver Protocol) that allows the Data Layer to communicate with a specific underlying storage engine.
81+
* *Example:* `@objectstack/driver-postgres`, `@objectstack/driver-mongodb`, `@objectstack/driver-sqlite`.
82+
83+
### AST (Abstract Syntax Tree)
84+
The intermediate representation of a query or schema. The Data Protocol parses a JSON request into an AST before the Driver translates it into SQL/NoSQL queries. This allows for security validation and optimization before execution.
85+
86+
### Manifest
87+
The entry point configuration file (Kernel Protocol) for an ObjectStack Plugin. It declares dependencies, resources, and extensions using the Manifest schema.
88+
89+
---
90+
91+
## Interface & Logic
92+
93+
### Layout
94+
A JSON structure defined in the UI Protocol that describes the visual arrangement of components. Layouts can be nested and dynamic (e.g., Master-Detail, Grid, Kanban).
95+
96+
### Workflow
97+
A business process (Automation Protocol) defined as a **Finite State Machine (FSM)**. It consists of States (e.g., `draft`, `approved`), Transitions, and Guards.
98+
99+
### Flow
100+
A visual logic automation tool (Automation Protocol) that allows building business processes using a node-based editor. Supports screen flows, autolaunched flows, and scheduled flows.
101+
102+
### Action
103+
A discrete unit of logic (UI Protocol) that can be triggered by a user (UI button) or a system event (Workflow transition). Actions define button behaviors and navigation.
104+
105+
### Component Registry
106+
A map within the UI Runtime that links a string identifier (e.g., `"chart.bar"`) to a real React Component. This allows the UI Protocol to instantiate UI elements dynamically.
107+
108+
---
109+
110+
## Governance
111+
112+
### Space (Workspace)
113+
A logical isolation unit (Hub Protocol) for multi-tenancy. A single ObjectStack instance can host multiple Spaces. Data is physically segregated by tenant isolation strategies.
114+
115+
### FLS (Field-Level Security)
116+
A granular permission model (Permission Protocol) where access control is applied to individual fields (columns), not just the whole object (row).
117+
118+
### OWD (Organization-Wide Defaults)
119+
The default sharing level (Permission Protocol) for records in an object. Determines the baseline access level before sharing rules are applied.
120+
121+
### Territory
122+
A hierarchical access control model (Permission Protocol) that grants data access based on geographic or organizational boundaries.
123+
124+
### TCK (Technology Compatibility Kit)
125+
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.

‎content/docs/getting-started/index.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ For more troubleshooting, see the [Troubleshooting & FAQ](/docs/guides/troublesh
137137

138138
## Next Steps
139139

140-
- [Design Principles](/docs/concepts/design-principles) - Understand the philosophy
141-
- [Architecture](/docs/concepts/architecture) - Deep dive into the system
142-
- [Glossary](/docs/concepts/terminology) - Learn key terminology
143-
- [Core Concepts](/docs/core-concepts) - Metadata-driven development explained
140+
- [Core Concepts](/docs/getting-started/core-concepts) — Metadata-driven development & design principles
141+
- [Architecture](/docs/getting-started/architecture) — The three-layer protocol stack
142+
- [Glossary](/docs/getting-started/glossary) — Key terminology
143+
- [Quick Start](/docs/getting-started/quick-start) — Build your first app in 5 minutes

‎content/docs/getting-started/meta.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"title": "Getting Started",
3-
"pages": ["index", "quick-start", "examples", "cli"]
3+
"pages": ["index", "quick-start", "core-concepts", "architecture", "examples", "cli", "glossary"]
44
}

‎content/docs/getting-started/quick-start.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -96,27 +96,27 @@ Follow these guides in order for the best experience:
9696
<Cards>
9797
<Card
9898
title="1. Data Modeling"
99-
href="./data-modeling"
99+
href="/docs/guides/data-modeling"
100100
description="Design objects, fields, relationships, and validation rules. The foundation of every app."
101101
/>
102102
<Card
103103
title="2. Business Logic"
104-
href="./business-logic"
104+
href="/docs/guides/business-logic"
105105
description="Implement workflows, approval flows, triggers, and formulas to automate business processes."
106106
/>
107107
<Card
108108
title="3. Security Model"
109-
href="./security"
109+
href="/docs/guides/security"
110110
description="Configure profiles, permissions, sharing rules, and row-level security for enterprise-grade access control."
111111
/>
112112
<Card
113113
title="4. AI Capabilities"
114-
href="./ai-capabilities"
114+
href="/docs/guides/ai-capabilities"
115115
description="Add AI agents, RAG pipelines, natural language queries, and predictive analytics."
116116
/>
117117
<Card
118118
title="5. Development Standards"
119-
href="./standards"
119+
href="/docs/guides/standards"
120120
description="Naming conventions, project structure, testing strategies, and best practices."
121121
/>
122122
</Cards>

content/docs/guides/backward-compatibility.mdx renamed to content/docs/guides/cheatsheets/backward-compatibility.mdx

File renamed without changes.

content/docs/guides/error-catalog.mdx renamed to content/docs/guides/cheatsheets/error-catalog.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ ObjectStack uses a structured error system with **9 error categories** and **41+
103103

104104
### `invalid_query`
105105
**Cause:** The query structure is malformed.
106-
**Fix:** Check the query syntax against the [Query Cheat Sheet](/references/data/query-cheat-sheet).
106+
**Fix:** Check the query syntax against the [Query Cheat Sheet](/docs/guides/cheatsheets/query-cheat-sheet).
107107
**Retry:** `no_retry`
108108

109109
### `invalid_filter`

content/docs/guides/field-type-decision-tree.mdx renamed to content/docs/guides/cheatsheets/field-type-decision-tree.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ description: Interactive guide for choosing the right ObjectStack field type —
88
Not sure which field type to use? Follow this decision tree to find the right type for your data, then check the quick-reference table for details.
99

1010
<Callout type="info">
11-
**Full Details:** Once you've identified the right type, see the [Field Type Gallery](/references/data/field-type-gallery) for complete configuration properties.
11+
**Full Details:** Once you've identified the right type, see the [Field Type Gallery](/docs/guides/cheatsheets/field-type-gallery) for complete configuration properties.
1212
</Callout>
1313

1414
---

content/docs/guides/field-type-gallery.mdx renamed to content/docs/guides/cheatsheets/field-type-gallery.mdx

File renamed without changes.

0 commit comments

Comments
 (0)