Skip to content

Commit 86a0c51

Browse files
Copilotxuyushun441-sys
Copilot
and
xuyushun441-sys
committed
Add example validation script and protocol quick reference guide
Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>
1 parent 2335f27 commit 86a0c51

2 files changed

Lines changed: 491 additions & 0 deletions

File tree

‎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%)

0 commit comments

Comments
 (0)