Skip to content

Commit 2b2fc7b

Browse files
hotlonghotlong
committed
Update README and add docs scripts to package.json
Revamps the README with clearer documentation, protocol architecture, and contribution guidelines. Adds documentation-related scripts (docs:dev, docs:build, docs:start) to package.json for easier management of the documentation site.
1 parent b597b07 commit 2b2fc7b

File tree

4 files changed

+99
-64
lines changed

4 files changed

+99
-64
lines changed

‎README.md‎

Lines changed: 55 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,85 @@
1-
# @objectstack/spec
1+
# ObjectStack Protocol
22

3+
![ObjectStack Protocol](https://img.shields.io/badge/ObjectStack-Protocol-black)
34
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
45
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
56

6-
> ObjectStack Protocol & Specification - The Constitution of the ObjectStack Ecosystem
7+
> **The "Constitution" of the Post-SaaS Operating System.**
78
8-
## 📜 Overview
9+
This repository contains the core specifications, schemas, and protocols that power the ObjectStack ecosystem. It defines how data, UI, and system configurations are expressed as code.
910

10-
This monorepo contains the **core interfaces, schemas, and conventions** for the ObjectStack ecosystem. It serves as the "Constitution" - the shared language that ObjectOS, ObjectStudio, ObjectCloud, and all third-party plugins use to communicate.
11+
## 📚 Documentation
1112

12-
**Guiding Principle:** *"Strict Types, No Logic"*
13+
The official documentation is co-located in this repository.
1314

14-
## 📦 Packages
15+
* **[Concepts](./content/docs/concepts/):** Architecture, Manifesto, and Core Values.
16+
* **[Specifications](./packages/spec/json-schema/):** Auto-generated JSON Schemas.
17+
* **[API Reference](./content/docs/references/):** Detailed property references generated from code.
1518

16-
This repository is organized as a monorepo with the following packages:
19+
## 📦 Monorepo Structure
1720

18-
### Core Packages
21+
| Package | Description | Status |
22+
| :--- | :--- | :--- |
23+
| **[`@objectstack/spec`](packages/spec)** | **THE PROTOCOL**. Contains all Zod definitions, Types, and JSON Schemas. | 🟢 **Active** |
24+
| `content/docs` | The documentation site source. | 🟢 **Active** |
25+
| *Other packages* | *Legacy/Migration in progress* | 🟡 *Legacy* |
1926

20-
- **[@objectstack/spec](./packages/spec)** - Main package that re-exports everything (use this for convenience)
21-
- **[@objectstack/spec-meta](./packages/meta)** - Metamodel type definitions (ObjectEntity, ObjectField, ObjectView)
22-
- **[@objectstack/spec-plugin](./packages/plugin)** - Plugin runtime interfaces (ObjectStackPlugin, PluginContext)
23-
- **[@objectstack/spec-schemas](./packages/schemas)** - Zod validation schemas (ManifestSchema, MenuItemSchema)
24-
- **[@objectstack/spec-constants](./packages/constants)** - Convention constants (PKG_CONVENTIONS)
27+
## 🛠️ The Protocol Architecture
2528

26-
## 🚀 Installation
29+
The ObjectStack Protocol (`@objectstack/spec`) is divided into three layers:
2730

28-
### Install the main package (recommended)
31+
### 1. Data Protocol (ObjectQL)
32+
Defines the "Shape of Data".
33+
- **Schema:** Objects, Fields, Validation.
34+
- **Logic:** Formulas, Rollups.
35+
- **Security:** Permissions, Sharing Rules.
36+
- **Query:** Abstract Syntax Tree (AST) for unified data access.
2937

30-
```bash
31-
pnpm install @objectstack/spec
32-
```
33-
34-
### Install individual packages (for smaller bundle sizes)
35-
36-
```bash
37-
pnpm install @objectstack/spec-meta
38-
pnpm install @objectstack/spec-plugin
39-
pnpm install @objectstack/spec-schemas
40-
pnpm install @objectstack/spec-constants
41-
```
38+
### 2. UI Protocol (ObjectUI)
39+
Defines the "Shape of Interaction".
40+
- **Views:** Grids, Kanbans, Calendars.
41+
- **Pages:** FlexiPage layouts (Regions & Components).
42+
- **Navigation:** Apps, Menus.
43+
- **Analytics:** Reports, Dashboards.
4244

43-
## 📚 Usage
45+
### 3. System Protocol (ObjectOS)
46+
Defines the "Runtime Environment".
47+
- **Manifest:** Application packaging (`objectstack.config.ts`).
48+
- **Identity:** Auth, Roles, Territories.
49+
- **Integration:** Webhooks, ETL Mappings.
4450

45-
### Using the main package
51+
## 🚀 Development
4652

47-
```typescript
48-
import {
49-
ObjectEntity,
50-
ObjectStackPlugin,
51-
ManifestSchema,
52-
PKG_CONVENTIONS
53-
} from '@objectstack/spec';
54-
```
55-
56-
### Using individual packages
53+
This project uses **PNPM** workspaces.
5754

58-
```typescript
59-
import { ObjectEntity } from '@objectstack/spec-meta';
60-
import { ObjectStackPlugin } from '@objectstack/spec-plugin';
61-
import { ManifestSchema } from '@objectstack/spec-schemas';
62-
import { PKG_CONVENTIONS } from '@objectstack/spec-constants';
63-
```
55+
### Prerequisites
56+
- Node.js >= 18
57+
- PNPM >= 8
6458

65-
## 🏗️ Development
59+
### Quick Start
6660

6761
```bash
68-
# Install dependencies
62+
# 1. Install dependencies
6963
pnpm install
7064

71-
# Build all packages
72-
pnpm run build
65+
# 2. Build the Protocol (Generates Schemas & Docs)
66+
pnpm --filter @objectstack/spec build
67+
# Output:
68+
# - packages/spec/dist/ (Compiled TS)
69+
# - packages/spec/json-schema/ (JSON Schemas)
70+
# - content/docs/references/ (Markdown Docs)
7371

74-
# Watch mode for development (all packages)
75-
pnpm run dev
76-
77-
# Clean build artifacts
78-
pnpm run clean
72+
# 3. Start Documentation Site (Optional)
73+
# (Assuming a doc site runner is configured)
74+
pnpm dev
7975
```
8076

81-
### Building Individual Packages
77+
## 🤝 Contribution
8278

83-
```bash
84-
# Build a specific package
85-
cd packages/meta && pnpm run build
86-
```
79+
1. **Code First**: Always start by defining the Zod Schema in `packages/spec/src`.
80+
2. **Generate**: Run `pnpm build` to update JSON Schemas and Documentation.
81+
3. **Commit**: Submit PR with updated Code + Schemas + Docs.
8782

8883
## 📄 License
8984

90-
MIT
85+
MIT © ObjectStack

‎content/docs.site.json‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,15 @@
2828
"transparentMode": "top",
2929
"links": [
3030
{
31-
"text": "Home",
31+
"text": "Concepts",
32+
"url": "/docs/concepts/manifesto"
33+
},
34+
{
35+
"text": "References",
36+
"url": "/docs/references/Object"
37+
},
38+
{
39+
"text": "Website",
3240
"url": "https://www.objectstack.ai",
3341
"external": true
3442
}

‎content/docs/references/meta.json‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,33 @@
11
{
22
"label": "API References",
3-
"order": 100
4-
}
3+
"order": 100,
4+
"pages": [
5+
"--- Data Protocol ---",
6+
"Object",
7+
"Field",
8+
"PermissionSet",
9+
"SharingRule",
10+
"Query",
11+
"Mapping",
12+
"Flow",
13+
"ValidationRule",
14+
15+
"--- UI Protocol ---",
16+
"App",
17+
"Page",
18+
"View",
19+
"Dashboard",
20+
"DashboardWidget",
21+
"Report",
22+
"Action",
23+
24+
"--- System Protocol ---",
25+
"Manifest",
26+
"Datasource",
27+
"Role",
28+
"Territory",
29+
"Policy",
30+
"Webhook",
31+
"TranslationBundle"
32+
]
33+
}

‎package.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,10 @@
88
"dev": "pnpm -r --parallel dev",
99
"clean": "pnpm -r --parallel clean && rm -rf dist",
1010
"version": "changeset version",
11-
"release": "pnpm run build && changeset publish"
11+
"release": "pnpm run build && changeset publish",
12+
"docs:dev": "objectdocs dev",
13+
"docs:build": "objectdocs build",
14+
"docs:start": "objectdocs start"
1215
},
1316
"keywords": [
1417
"objectstack",

0 commit comments

Comments
 (0)