Skip to content

Commit 4551a72

Browse files
hotlonghotlong
authored
Merge pull request #425 from objectstack-ai/copilot/update-examples-and-test-platform
2 parents b8e2bfd + 523849b commit 4551a72

24 files changed

+4575
-9
lines changed

‎PROTOCOL-QUICK-REFERENCE.md‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
# ObjectStack Protocol Quick Reference
2+
3+
> **Fast lookup guide for developers** - organized by protocol category
4+
5+
## 📖 How to Use This Guide
6+
7+
- **Find by Category**: Browse protocols by domain (Data, UI, System, etc.)
8+
- **Find by Example**: Every protocol links to practical examples
9+
- **Find by Feature**: Use the index to jump to specific features
10+
11+
---
12+
13+
## 🗂️ Protocol Index
14+
15+
### Data Protocol (ObjectQL)
16+
17+
| Protocol | Description | Example | Status |
18+
|----------|-------------|---------|--------|
19+
| **Object** | Object definition with fields and relationships | [CRM Objects](./examples/crm/src/domains/crm/), [Todo](./examples/todo/) | ✅ |
20+
| **Field** | 28 field types (text, number, lookup, formula, etc.) | [CRM Account](./examples/crm/src/domains/crm/account.object.ts) | ✅ |
21+
| **Validation** | Validation rules (required, unique, format, script) | [CRM Examples](./examples/crm/), [Basic](./examples/basic/stack-definition-example.ts) | ✅ |
22+
| **Query** | Query language (filter, sort, pagination) | [Basic](./examples/basic/) | ✅ |
23+
| **Filter** | Filter expressions and operators | [Basic](./examples/basic/) | ✅ |
24+
| **Hook** | Before/after CRUD hooks | [CRM Hooks](./examples/crm/src/domains/crm/account.hook.ts) | ✅ |
25+
| **Driver** | Database driver abstraction | [Basic](./examples/basic/) | ✅ |
26+
| **External Lookup** | Lookup fields from external systems | [Plugin BI](./examples/plugin-bi/) | 🟡 |
27+
| **Document** | Document storage (NoSQL) | _Planned_ | 🔴 |
28+
| **Dataset** | Virtual datasets and views | [Basic](./examples/basic/) | 🟡 |
29+
| **Mapping** | Field mapping and transformation | [Basic](./examples/basic/) | 🟡 |
30+
31+
### UI Protocol (ObjectUI)
32+
33+
| Protocol | Description | Example | Status |
34+
|----------|-------------|---------|--------|
35+
| **View** | List and form views (grid, kanban, calendar, gantt) | [CRM](./examples/crm/) | ✅ |
36+
| **App** | Application definition and navigation | [CRM](./examples/crm/objectstack.config.ts), [Basic](./examples/basic/stack-definition-example.ts) | ✅ |
37+
| **Action** | Custom actions (script, URL, modal, flow) | [CRM Actions](./examples/crm/src/ui/actions.ts) | ✅ |
38+
| **Dashboard** | Dashboard with widgets | [CRM Dashboards](./examples/crm/src/ui/dashboards.ts) | ✅ |
39+
| **Report** | Reports (tabular, summary, matrix, chart) | [CRM Reports](./examples/crm/src/ui/reports.ts) | ✅ |
40+
| **Chart** | Chart types (bar, line, pie, donut, funnel) | [CRM](./examples/crm/), [Plugin BI](./examples/plugin-bi/) | ✅ |
41+
| **Widget** | Dashboard widgets | [CRM Dashboards](./examples/crm/src/ui/dashboards.ts) | ✅ |
42+
| **Theme** | Visual theming and branding | [Basic](./examples/basic/) | 🟡 |
43+
| **Page** | Custom pages | [Basic](./examples/basic/) | 🟡 |
44+
| **Component** | Reusable UI components | _Planned_ | 🔴 |
45+
46+
### System Protocol (ObjectOS)
47+
48+
| Protocol | Description | Example | Status |
49+
|----------|-------------|---------|--------|
50+
| **Manifest** | Package/plugin manifest | All `objectstack.config.ts` files | ✅ |
51+
| **Plugin** | Plugin system | [Plugin Advanced CRM](./examples/plugin-advanced-crm/), [Host](./examples/host/) | ✅ |
52+
| **Capabilities** | Runtime capability declaration | [Basic Capabilities](./examples/basic/capabilities-example.ts) | ✅ |
53+
| **Logging** | Structured logging | [Basic Logger](./examples/basic/logger-example.ts) | ✅ |
54+
| **Events** | Event bus and pub/sub | [Middleware](./examples/middleware-example.ts) | ✅ |
55+
| **Service Registry** | Service discovery and registration | [Plugin Advanced CRM](./examples/plugin-advanced-crm/) | ✅ |
56+
| **Job** | Background job scheduling | [System Protocols](./examples/basic/system-protocols-example.ts) | ✅ |
57+
| **Metrics** | Metrics and monitoring (Prometheus, StatsD) | [System Protocols](./examples/basic/system-protocols-example.ts) | ✅ |
58+
| **Tracing** | Distributed tracing (OpenTelemetry, Jaeger) | [System Protocols](./examples/basic/system-protocols-example.ts) | ✅ |
59+
| **Cache** | Multi-level caching (Memory, Redis) | [System Protocols](./examples/basic/system-protocols-example.ts) | ✅ |
60+
| **Audit** | Audit logging | [System Protocols](./examples/basic/system-protocols-example.ts) | ✅ |
61+
| **Compliance** | Compliance controls (GDPR, HIPAA, SOC 2) | [System Protocols](./examples/basic/system-protocols-example.ts) | ✅ |
62+
| **Encryption** | Encryption at rest and in transit | [System Protocols](./examples/basic/system-protocols-example.ts) | ✅ |
63+
| **Datasource** | External datasource configuration | [Basic](./examples/basic/) | 🟡 |
64+
| **Translation** | Internationalization (i18n) | [Basic](./examples/basic/) | 🟡 |
65+
| **Notification** | Notification system | _Planned_ | 🔴 |
66+
| **Object Storage** | File/object storage | _Planned_ | 🔴 |
67+
| **Search Engine** | Full-text search | _Planned_ | 🔴 |
68+
| **Message Queue** | Message queue integration | _Planned_ | 🔴 |
69+
70+
### AI Protocol
71+
72+
| Protocol | Description | Example | Status |
73+
|----------|-------------|---------|--------|
74+
| **Agent** | AI agent definition | [AI Sales](./examples/ai-sales/), [AI Support](./examples/ai-support/) | ✅ |
75+
| **RAG Pipeline** | Retrieval-Augmented Generation | [AI Support](./examples/ai-support/), [Basic RAG](./examples/basic/ai-rag-example.ts) | ✅ |
76+
| **Model Registry** | LLM configuration and routing | [AI Support](./examples/ai-support/) | ✅ |
77+
| **NLQ** | Natural Language Query | [AI Analyst](./examples/ai-analyst/) | ✅ |
78+
| **Conversation** | Conversation management | [AI Sales](./examples/ai-sales/) | ✅ |
79+
| **Orchestration** | AI workflow orchestration | [AI Codegen](./examples/ai-codegen/) | ✅ |
80+
| **Cost** | Cost tracking and budgeting | [AI Examples](./examples/ai-support/) | 🟡 |
81+
| **Predictive** | Predictive analytics | _Planned_ | 🔴 |
82+
| **Agent Action** | Agent tool calling | [AI Examples](./examples/) | ✅ |
83+
84+
### Automation Protocol
85+
86+
| Protocol | Description | Example | Status |
87+
|----------|-------------|---------|--------|
88+
| **Workflow** | Workflow rules and automation | [CRM](./examples/crm/), [Basic Automation](./examples/basic/automation-example.ts) | ✅ |
89+
| **Flow** | Visual flow builder (Screen flows) | [Basic Automation](./examples/basic/automation-example.ts) | ✅ |
90+
| **Approval** | Multi-step approval processes | [Basic Automation](./examples/basic/automation-example.ts) | ✅ |
91+
| **ETL** | ETL pipelines | [Basic Automation](./examples/basic/automation-example.ts) | ✅ |
92+
| **Trigger** | Event triggers | [CRM](./examples/crm/) | ✅ |
93+
| **Webhook** | Webhook configuration | [Basic](./examples/basic/) | 🟡 |
94+
| **Sync** | Data synchronization | _Planned_ | 🔴 |
95+
96+
### Auth & Permissions
97+
98+
| Protocol | Description | Example | Status |
99+
|----------|-------------|---------|--------|
100+
| **Identity** | User identity and sessions | [Basic Auth](./examples/basic/auth-permission-example.ts) | ✅ |
101+
| **Role** | Role-based access control (RBAC) | [Basic Auth](./examples/basic/auth-permission-example.ts) | ✅ |
102+
| **Permission** | Object and field-level permissions | [Basic Auth](./examples/basic/auth-permission-example.ts), [CRM](./examples/crm/) | ✅ |
103+
| **RLS** | Row-level security | [Basic Auth](./examples/basic/auth-permission-example.ts) | ✅ |
104+
| **Sharing** | Sharing rules | [Basic Auth](./examples/basic/auth-permission-example.ts) | ✅ |
105+
| **Territory** | Territory management | [Basic Auth](./examples/basic/auth-permission-example.ts) | ✅ |
106+
| **Config** | Auth provider configuration (OAuth, SAML) | [Plugin Advanced CRM](./examples/plugin-advanced-crm/) | 🟡 |
107+
| **SCIM** | SCIM provisioning | _Planned_ | 🔴 |
108+
| **Organization** | Organization management | _Planned_ | 🔴 |
109+
| **Policy** | Security policies | [Basic Auth](./examples/basic/auth-permission-example.ts) | ✅ |
110+
111+
### API Protocol
112+
113+
| Protocol | Description | Example | Status |
114+
|----------|-------------|---------|--------|
115+
| **REST Server** | REST API server | [REST Server](./examples/rest-server-example.ts), [Host](./examples/host/) | ✅ |
116+
| **GraphQL** | GraphQL API | [API Protocols](./examples/basic/api-protocols-example.ts) | ✅ |
117+
| **OData** | OData API | [API Protocols](./examples/basic/api-protocols-example.ts) | ✅ |
118+
| **WebSocket** | WebSocket/Real-time API | [API Protocols](./examples/basic/api-protocols-example.ts) | ✅ |
119+
| **Realtime** | Real-time subscriptions and live queries | [API Protocols](./examples/basic/api-protocols-example.ts) | ✅ |
120+
| **Batch** | Batch operations | [API Protocols](./examples/basic/api-protocols-example.ts) | ✅ |
121+
| **Discovery** | API discovery and introspection | [Basic Discovery](./examples/basic/api-discovery-example.ts) | ✅ |
122+
| **Contract** | API contracts | [Basic](./examples/basic/) | 🟡 |
123+
| **Endpoint** | Endpoint definition | [Basic](./examples/basic/) | 🟡 |
124+
| **Router** | API routing | [Basic](./examples/basic/) | 🟡 |
125+
| **Errors** | Error handling | [REST Server](./examples/rest-server-example.ts) | 🟡 |
126+
| **HTTP Cache** | HTTP caching | _Planned_ | 🔴 |
127+
128+
### Integration Protocol
129+
130+
| Protocol | Description | Example | Status |
131+
|----------|-------------|---------|--------|
132+
| **Connector** | External system connectors | [Integration Connectors](./examples/basic/integration-connectors-example.ts) | ✅ |
133+
| **Database** | Database connectors (Postgres, MySQL, MongoDB) | [Integration Connectors](./examples/basic/integration-connectors-example.ts) | ✅ |
134+
| **File Storage** | File storage connectors (S3, Azure Blob) | [Integration Connectors](./examples/basic/integration-connectors-example.ts) | ✅ |
135+
| **Message Queue** | Message queue connectors (RabbitMQ, Kafka, Redis) | [Integration Connectors](./examples/basic/integration-connectors-example.ts) | ✅ |
136+
| **SaaS** | SaaS connectors (Salesforce, HubSpot, Stripe) | [Integration Connectors](./examples/basic/integration-connectors-example.ts) | ✅ |
137+
138+
### Hub & Marketplace
139+
140+
| Protocol | Description | Example | Status |
141+
|----------|-------------|---------|--------|
142+
| **Plugin Registry** | Plugin publishing and discovery | [Hub & Marketplace](./examples/basic/hub-marketplace-example.ts) | ✅ |
143+
| **Marketplace** | Commercial plugin distribution | [Hub & Marketplace](./examples/basic/hub-marketplace-example.ts) | ✅ |
144+
| **License** | License management | [Hub & Marketplace](./examples/basic/hub-marketplace-example.ts) | ✅ |
145+
| **Tenant** | Multi-tenancy and isolation | [Hub & Marketplace](./examples/basic/hub-marketplace-example.ts) | ✅ |
146+
| **Space** | Team workspaces | [Hub & Marketplace](./examples/basic/hub-marketplace-example.ts) | ✅ |
147+
| **Composer** | Visual app builder (no-code/low-code) | [Hub & Marketplace](./examples/basic/hub-marketplace-example.ts) | ✅ |
148+
149+
---
150+
151+
## 🎯 Common Patterns
152+
153+
### Basic CRUD Object
154+
```typescript
155+
import { defineStack } from '@objectstack/spec';
156+
157+
const stack = defineStack({
158+
manifest: { id: 'my-app', type: 'app', name: 'my-app', version: '1.0.0' },
159+
objects: [{
160+
name: 'task',
161+
label: 'Task',
162+
fields: {
163+
subject: { type: 'text', label: 'Subject', required: true },
164+
status: {
165+
type: 'select',
166+
label: 'Status',
167+
options: [
168+
{ value: 'todo', label: 'To Do' },
169+
{ value: 'done', label: 'Done' }
170+
]
171+
}
172+
}
173+
}]
174+
});
175+
```
176+
177+
### Relationships
178+
```typescript
179+
// Master-Detail (Cascade delete)
180+
{
181+
type: 'lookup',
182+
label: 'Account',
183+
reference: { object: 'account' },
184+
relationshipType: 'master_detail',
185+
}
186+
187+
// Lookup (Regular reference)
188+
{
189+
type: 'lookup',
190+
label: 'Owner',
191+
reference: { object: 'user' },
192+
relationshipType: 'lookup',
193+
}
194+
```
195+
196+
### Formulas
197+
```typescript
198+
{
199+
type: 'formula',
200+
label: 'Full Name',
201+
returnType: 'text',
202+
formula: 'CONCATENATE(first_name, " ", last_name)',
203+
}
204+
```
205+
206+
### Validation Rules
207+
```typescript
208+
validation: {
209+
rules: [
210+
{
211+
name: 'positive_revenue',
212+
errorMessage: 'Revenue must be positive',
213+
formula: 'annual_revenue > 0',
214+
}
215+
]
216+
}
217+
```
218+
219+
### Workflows
220+
```typescript
221+
workflows: [
222+
{
223+
name: 'update_last_activity',
224+
triggerType: 'on_create_or_update',
225+
conditions: { field: 'status', operator: 'equals', value: 'closed' },
226+
actions: [
227+
{
228+
type: 'field_update',
229+
field: 'last_activity_date',
230+
value: 'TODAY()',
231+
}
232+
]
233+
}
234+
]
235+
```
236+
237+
---
238+
239+
## 📚 Learning Paths
240+
241+
### 🟢 Beginner Path (1-2 hours)
242+
1. [Todo Example](./examples/todo/) - Simple complete app
243+
2. [Stack Definition](./examples/basic/stack-definition-example.ts) - Configuration patterns
244+
3. [CRM Example](./examples/crm/) - Enterprise patterns
245+
246+
### 🟡 Intermediate Path (1-2 days)
247+
1. Complete Beginner Path
248+
2. [All Basic Examples](./examples/basic/) - Master each protocol
249+
3. [Plugin Advanced CRM](./examples/plugin-advanced-crm/) - Plugin development
250+
4. [MSW React CRUD](./examples/msw-react-crud/) - Frontend integration
251+
252+
### 🔴 Advanced Path (2-3 days)
253+
1. Complete Beginner & Intermediate Paths
254+
2. [AI Examples](./examples/) - AI integration patterns
255+
3. [Integration Connectors](./examples/basic/integration-connectors-example.ts) - External systems
256+
4. [System Protocols](./examples/basic/system-protocols-example.ts) - Production patterns
257+
5. [Host Server](./examples/host/) - Backend implementation
258+
259+
---
260+
261+
## 🔗 Resources
262+
263+
- **[Full Examples Catalog](./examples/README.md)** - Complete examples guide
264+
- **[Architecture Guide](./ARCHITECTURE.md)** - System architecture
265+
- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute
266+
- **[Protocol Specifications](./packages/spec/)** - Detailed protocol docs
267+
268+
---
269+
270+
**Version:** 0.6.1
271+
**Last Updated:** 2026-01-31
272+
**Protocol Coverage:** 75/108 (69%)

‎README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,14 +34,24 @@ ObjectStack is a metadata-driven platform built on three foundational protocols:
3434

3535
- **Getting Started:**
3636
- [Introduction](./content/docs/introduction/) - Core concepts and architecture
37-
- [Quick Start Examples](./examples/) - CRM, Todo, and plugin examples
37+
- [📚 Examples Catalog](./examples/README.md) - **Comprehensive examples for all protocols**
38+
- [Quick Start: Todo App](./examples/todo/) - Simplest complete example
39+
- [Quick Start: Basic Examples](./examples/basic/) - Protocol-by-protocol examples
3840

3941
- **Protocol References:**
4042
- [Protocol Reference](./content/docs/references/) - All 109 protocol specifications
4143
- [ObjectQL](./content/docs/objectql/) - Data layer documentation
4244
- [ObjectUI](./content/docs/objectui/) - UI layer documentation
4345
- [ObjectOS](./content/docs/objectos/) - System layer documentation
4446

47+
- **Examples by Use Case:**
48+
- [CRM Example](./examples/crm/) - Full-featured enterprise CRM
49+
- [AI Examples](./examples/) - AI Sales, Support, Analyst, Codegen
50+
- [Integration Examples](./examples/basic/integration-connectors-example.ts) - External system connectors
51+
- [System Examples](./examples/basic/system-protocols-example.ts) - Production-grade patterns
52+
- [API Examples](./examples/basic/api-protocols-example.ts) - GraphQL, OData, WebSocket
53+
- [Hub Examples](./examples/basic/hub-marketplace-example.ts) - Marketplace & Plugins
54+
4555
- **Development:**
4656
- [Architecture Guide](./ARCHITECTURE.md) - Complete architecture overview
4757
- [MicroKernel Architecture](./content/docs/developers/micro-kernel.mdx) - Plugin architecture guide

‎content/docs/references/api/batch.mdx‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,27 @@ description: Batch protocol schemas
1212
## TypeScript Usage
1313

1414
```typescript
15-
import { BatchOperationResultSchema, BatchOperationTypeSchema, BatchOptionsSchema, BatchRecordSchema, BatchUpdateRequestSchema, BatchUpdateResponseSchema, DeleteManyRequestSchema, UpdateManyRequestSchema } from '@objectstack/spec/api';
16-
import type { BatchOperationResult, BatchOperationType, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, DeleteManyRequest, UpdateManyRequest } from '@objectstack/spec/api';
15+
import { BatchConfigSchema, BatchOperationResultSchema, BatchOperationTypeSchema, BatchOptionsSchema, BatchRecordSchema, BatchUpdateRequestSchema, BatchUpdateResponseSchema, DeleteManyRequestSchema, UpdateManyRequestSchema } from '@objectstack/spec/api';
16+
import type { BatchConfig, BatchOperationResult, BatchOperationType, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, DeleteManyRequest, UpdateManyRequest } from '@objectstack/spec/api';
1717

1818
// Validate data
19-
const result = BatchOperationResultSchema.parse(data);
19+
const result = BatchConfigSchema.parse(data);
2020
```
2121

2222
---
2323

24+
## BatchConfig
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **enabled** | `boolean` | optional | Enable batch operations |
31+
| **maxRecordsPerBatch** | `integer` | optional | Maximum records per batch |
32+
| **defaultOptions** | `object` | optional | Default batch options |
33+
34+
---
35+
2436
## BatchOperationResult
2537

2638
### Properties

‎content/docs/references/api/odata.mdx‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,27 @@ description: Odata protocol schemas
1212
## TypeScript Usage
1313

1414
```typescript
15-
import { ODataErrorSchema, ODataFilterFunctionSchema, ODataFilterOperatorSchema, ODataMetadataSchema, ODataQuerySchema, ODataResponseSchema } from '@objectstack/spec/api';
16-
import type { ODataError, ODataFilterFunction, ODataFilterOperator, ODataMetadata, ODataQuery, ODataResponse } from '@objectstack/spec/api';
15+
import { ODataConfigSchema, ODataErrorSchema, ODataFilterFunctionSchema, ODataFilterOperatorSchema, ODataMetadataSchema, ODataQuerySchema, ODataResponseSchema } from '@objectstack/spec/api';
16+
import type { ODataConfig, ODataError, ODataFilterFunction, ODataFilterOperator, ODataMetadata, ODataQuery, ODataResponse } from '@objectstack/spec/api';
1717

1818
// Validate data
19-
const result = ODataErrorSchema.parse(data);
19+
const result = ODataConfigSchema.parse(data);
2020
```
2121

2222
---
2323

24+
## ODataConfig
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **enabled** | `boolean` | optional | Enable OData API |
31+
| **path** | `string` | optional | OData endpoint path |
32+
| **metadata** | `object` | optional | OData metadata configuration |
33+
34+
---
35+
2436
## ODataError
2537

2638
### Properties

‎content/docs/references/api/realtime.mdx‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ description: Realtime protocol schemas
1212
## TypeScript Usage
1313

1414
```typescript
15-
import { PresenceSchema, PresenceStatusSchema, RealtimeActionSchema, RealtimeEventSchema, RealtimeEventTypeSchema, SubscriptionSchema, SubscriptionEventSchema, TransportProtocolSchema } from '@objectstack/spec/api';
16-
import type { Presence, PresenceStatus, RealtimeAction, RealtimeEvent, RealtimeEventType, Subscription, SubscriptionEvent, TransportProtocol } from '@objectstack/spec/api';
15+
import { PresenceSchema, PresenceStatusSchema, RealtimeActionSchema, RealtimeConfigSchema, RealtimeEventSchema, RealtimeEventTypeSchema, SubscriptionSchema, SubscriptionEventSchema, TransportProtocolSchema } from '@objectstack/spec/api';
16+
import type { Presence, PresenceStatus, RealtimeAction, RealtimeConfig, RealtimeEvent, RealtimeEventType, Subscription, SubscriptionEvent, TransportProtocol } from '@objectstack/spec/api';
1717

1818
// Validate data
1919
const result = PresenceSchema.parse(data);
@@ -54,6 +54,18 @@ const result = PresenceSchema.parse(data);
5454

5555
---
5656

57+
## RealtimeConfig
58+
59+
### Properties
60+
61+
| Property | Type | Required | Description |
62+
| :--- | :--- | :--- | :--- |
63+
| **enabled** | `boolean` | optional | Enable realtime synchronization |
64+
| **transport** | `Enum<'websocket' \| 'sse' \| 'polling'>` | optional | Transport protocol |
65+
| **subscriptions** | `object[]` | optional | Default subscriptions |
66+
67+
---
68+
5769
## RealtimeEvent
5870

5971
### Properties

0 commit comments

Comments
 (0)