Skip to content

Update documentation to reflect current protocol implementation #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hotlong merged 6 commits into from
Jan 20, 2026
Merged

Update documentation to reflect current protocol implementation #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
21ae2c0
Initial plan
Copilot Jan 20, 2026
24ae995
Add comprehensive field types guide and update READMEs
Copilot Jan 20, 2026
0105d71
Update Getting Started guides with comprehensive examples
Copilot Jan 20, 2026
1fecbe6
Add comprehensive Workflows and Validation Rules guide
Copilot Jan 20, 2026
a4ba6fc
Add comprehensive View Configuration guide
Copilot Jan 20, 2026
7b8576e
Update documentation index pages with new guides and architecture
Copilot Jan 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 39 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,31 +29,55 @@ The official documentation is built with Fumadocs and Next.js.
| **[`@objectstack/spec`](packages/spec)** | **THE PROTOCOL**. Contains all Zod definitions, Types, and JSON Schemas. | 🟢 **Active** |
| **[`@objectstack/docs`](apps/docs)** | Documentation site built with Fumadocs and Next.js. | 🟢 **Active** |
| `content/docs/` | Documentation content (MDX files). Shared resource. | 🟢 **Active** |
| **Examples** | Reference implementations demonstrating protocol features | |
| └─ [`examples/crm`](examples/crm) | **Full-featured CRM** - 6 objects, workflows, validations, views, dashboards, reports | 🟢 **Complete** |
| └─ [`examples/todo`](examples/todo) | **Quick-start** - Simple task management with 7 field types | 🟢 **Active** |
| └─ [`examples/host`](examples/host) | Server runtime with kernel/plugin loading pattern | 🟡 **Experimental** |
| └─ [`examples/plugin-bi`](examples/plugin-bi) | Business Intelligence plugin example | 🟡 **Experimental** |
| *Other packages* | *Legacy/Migration in progress* | 🟡 *Legacy* |

## 🛠️ The Protocol Architecture

The ObjectStack Protocol (`@objectstack/spec`) is divided into three layers:
The ObjectStack Protocol (`@objectstack/spec`) is divided into five core modules:

### 1. Data Protocol (ObjectQL)
Defines the "Shape of Data".
- **Schema:** Objects, Fields, Validation.
- **Logic:** Formulas, Rollups.
- **Security:** Permissions, Sharing Rules.
- **Query:** Abstract Syntax Tree (AST) for unified data access.
Defines the "Shape of Data" and business logic.
- **Schema:** Objects, Fields (23+ types including text, number, select, lookup, formula, autonumber, etc.)
Copy link

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The architecture description mentions "23+ types" on line 45, but the field-types guide and the actual protocol implementation (field.zod.ts) shows 30+ field types. This count should be updated to "30+ field types" for accuracy and consistency with the documentation guides.

Suggested change
- **Schema:** Objects, Fields (23+ types including text, number, select, lookup, formula, autonumber, etc.)
- **Schema:** Objects, Fields (30+ field types including text, number, select, lookup, formula, autonumber, etc.)

Copilot uses AI. Check for mistakes.
- **Logic:** Workflows, Triggers, Validation Rules, Formulas
- **Security:** Permissions, Sharing Rules
- **Query:** Abstract Syntax Tree (AST) for unified data access across drivers
- **Automation:** Flow definitions, Dataset mappings

### 2. UI Protocol (ObjectUI)
Defines the "Shape of Interaction".
- **Views:** Grids, Kanbans, Calendars.
- **Pages:** FlexiPage layouts (Regions & Components).
- **Navigation:** Apps, Navigation.
- **Analytics:** Reports, Dashboards.
Defines the "Shape of Interaction" for rendering interfaces.
- **Views:** Grid, Kanban, Calendar, Gantt, List configurations
- **Pages:** FlexiPage layouts with regions and components
- **Navigation:** App menus and navigation structures
- **Analytics:** Reports (Tabular, Summary, Matrix), Dashboards with widgets
- **Actions:** Script, URL, Modal, Flow-triggered actions
- **Theming:** Color palettes, typography, breakpoints, animations

### 3. System Protocol (ObjectOS)
Defines the "Runtime Environment".
- **Manifest:** Application packaging (`objectstack.config.ts`).
- **Identity:** Auth, Roles, Territories.
- **Integration:** Webhooks, ETL Mappings.
Defines the "Runtime Environment" and platform capabilities.
- **Manifest:** Application packaging (`objectstack.config.ts`)
- **Identity:** Authentication, Roles, Territories, Licenses
- **Integration:** Webhooks, API contracts, ETL Mappings
- **Datasource:** Driver definitions for SQL, NoSQL, SaaS connectors
- **Discovery:** Plugin discovery and loading mechanisms
- **I18n:** Translation and internationalization support

### 4. AI Protocol
Defines AI agent integration capabilities.
- **Agent:** AI agent definitions and configurations
- **Tools:** AI tool integrations
- **Knowledge:** Knowledge base structures
- **Models:** AI model configurations

### 5. API Protocol
Defines standardized API contracts.
- **Envelopes:** Response structures (BaseResponse, ListRecordResponse, etc.)
- **Requests:** Request payloads (CreateRequest, UpdateRequest, BulkRequest, etc.)
- **Contracts:** API endpoint definitions and specifications

## 🚀 Development

Expand Down
Loading