Skip to content

Commit 25c5f7f

Browse files
Copilotxuyushun441-sys
Copilot
and
xuyushun441-sys
committed
Add protocol organization diagrams and cross-references
Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>
1 parent 951a710 commit 25c5f7f

File tree

3 files changed

+248
-0
lines changed

3 files changed

+248
-0
lines changed

‎PROTOCOL_ORGANIZATION.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
# ObjectStack Protocol Organization
2+
3+
This document provides a visual map of how the 70 protocol specifications are organized across the ObjectStack ecosystem.
4+
5+
```
6+
objectstack-ai/spec
7+
└── packages/spec/src/
8+
│
9+
├── 📊 DATA PROTOCOL (ObjectQL) - 8 files
10+
│ ├── field.zod.ts → 44 field types (text, number, vector, location, etc.)
11+
│ ├── object.zod.ts → Object/table definitions with fields and indexes
12+
│ ├── query.zod.ts → Query AST (window functions, HAVING, DISTINCT, subqueries)
13+
│ ├── validation.zod.ts → Validation rules for data integrity
14+
│ ├── filter.zod.ts → Query filters and conditions
15+
│ ├── dataset.zod.ts → Dataset definitions for analytics
16+
│ ├── mapping.zod.ts → Field mapping for data transformation
17+
│ └── hook.zod.ts → Lifecycle hooks (before/after CRUD)
18+
│
19+
├── 🎨 UI PROTOCOL (ObjectUI) - 10 files
20+
│ ├── view.zod.ts → List views (grid, kanban, calendar, gantt)
21+
│ ├── page.zod.ts → FlexiPage layouts with regions
22+
│ ├── app.zod.ts → Application navigation menus
23+
│ ├── dashboard.zod.ts → Dashboard layouts with widgets
24+
│ ├── report.zod.ts → Report definitions (tabular, summary, matrix, chart)
25+
│ ├── action.zod.ts → UI actions (buttons, scripts, flows)
26+
│ ├── component.zod.ts → Reusable UI components
27+
│ ├── block.zod.ts → UI block definitions
28+
│ ├── theme.zod.ts → Theming (colors, typography, animations)
29+
│ └── widget.zod.ts → Custom field widgets
30+
│
31+
├── ⚙️ SYSTEM PROTOCOL (ObjectOS) - 14 files
32+
│ ├── manifest.zod.ts → Package manifest (objectstack.config.ts)
33+
│ ├── datasource.zod.ts → Data source connections
34+
│ ├── driver.zod.ts → Database driver definitions
35+
│ ├── driver/
36+
│ │ ├── postgres.zod.ts → PostgreSQL driver config
37+
│ │ └── mongo.zod.ts → MongoDB driver config
38+
│ ├── plugin.zod.ts → Plugin lifecycle and interface
39+
│ ├── context.zod.ts → Kernel execution context
40+
│ ├── events.zod.ts → Event bus and pub/sub
41+
│ ├── job.zod.ts → Background job scheduling
42+
│ ├── audit.zod.ts → Audit logging
43+
│ ├── logger.zod.ts → Structured logging
44+
│ ├── translation.zod.ts → i18n/l10n support
45+
│ ├── feature.zod.ts → Feature flags
46+
│ └── scoped-storage.zod.ts → Key-value storage
47+
│
48+
├── 🤖 AI PROTOCOL - 8 files
49+
│ ├── agent.zod.ts → AI agent definitions
50+
│ ├── model-registry.zod.ts → LLM model registry
51+
│ ├── rag-pipeline.zod.ts → Retrieval-augmented generation
52+
│ ├── nlq.zod.ts → Natural language query (NL → ObjectQL)
53+
│ ├── conversation.zod.ts → Conversation management
54+
│ ├── cost.zod.ts → AI cost tracking
55+
│ ├── predictive.zod.ts → Predictive analytics/ML models
56+
│ └── orchestration.zod.ts → AI workflow orchestration
57+
│
58+
├── 🌐 API PROTOCOL - 6 files
59+
│ ├── contract.zod.ts → API contracts and specifications
60+
│ ├── endpoint.zod.ts → REST endpoints with rate limiting
61+
│ ├── router.zod.ts → API routing
62+
│ ├── odata.zod.ts → OData query protocol
63+
│ ├── realtime.zod.ts → WebSocket/SSE subscriptions
64+
│ └── discovery.zod.ts → API discovery/introspection
65+
│
66+
├── 🔄 AUTOMATION PROTOCOL - 7 files
67+
│ ├── flow.zod.ts → Visual workflow builder
68+
│ ├── workflow.zod.ts → Declarative workflow rules
69+
│ ├── approval.zod.ts → Multi-step approval processes
70+
│ ├── webhook.zod.ts → Outbound webhooks
71+
│ ├── etl.zod.ts → ETL data pipelines
72+
│ ├── sync.zod.ts → Bi-directional data sync
73+
│ └── connector.zod.ts → External system connectors
74+
│
75+
├── 🔐 AUTH PROTOCOL - 6 files
76+
│ ├── identity.zod.ts → User identity and profiles
77+
│ ├── role.zod.ts → Role definitions (RBAC)
78+
│ ├── organization.zod.ts → Multi-org structure
79+
│ ├── policy.zod.ts → Password and session policies
80+
│ ├── config.zod.ts → OAuth/SAML/SSO configs
81+
│ └── scim.zod.ts → SCIM 2.0 provisioning
82+
│
83+
├── 🔒 PERMISSION PROTOCOL - 4 files
84+
│ ├── permission.zod.ts → Object-level CRUD permissions
85+
│ ├── sharing.zod.ts → Sharing rules (criteria & manual)
86+
│ ├── rls.zod.ts → Row-level security
87+
│ └── territory.zod.ts → Territory management
88+
│
89+
├── 🏪 HUB PROTOCOL - 5 files
90+
│ ├── marketplace.zod.ts → Plugin marketplace listings
91+
│ ├── composer.zod.ts → Package dependency management
92+
│ ├── license.zod.ts → Feature licensing
93+
│ ├── tenant.zod.ts → Multi-tenant isolation
94+
│ └── space.zod.ts → Workspace/space management
95+
│
96+
├── 🔧 SHARED PROTOCOL - 1 file
97+
│ └── identifiers.zod.ts → Standard identifier formats
98+
│
99+
└── 📦 STACK PROTOCOL - 1 file
100+
└── stack.zod.ts → Root stack definition (combines all protocols)
101+
```
102+
103+
## Protocol Layers
104+
105+
```
106+
┌─────────────────────────────────────────────────────────────┐
107+
│ STACK PROTOCOL (1) │
108+
│ Unified Stack Configuration │
109+
└─────────────────────────────────────────────────────────────┘
110+
▼
111+
┌─────────────────────────────────────────────────────────────┐
112+
│ APPLICATION LAYER │
113+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
114+
│ │ AUTOMATION │ │ HUB │ │ AI │ │
115+
│ │ (7 specs) │ │ (5 specs) │ │ (8 specs) │ │
116+
│ └─────────────┘ └─────────────┘ └─────────────┘ │
117+
└─────────────────────────────────────────────────────────────┘
118+
▼
119+
┌─────────────────────────────────────────────────────────────┐
120+
│ PRESENTATION LAYER │
121+
│ ┌─────────────────────────────────────────────────────┐ │
122+
│ │ UI PROTOCOL (10 specs) │ │
123+
│ │ Views, Pages, Apps, Dashboards, Reports, etc. │ │
124+
│ └─────────────────────────────────────────────────────┘ │
125+
└─────────────────────────────────────────────────────────────┘
126+
▼
127+
┌─────────────────────────────────────────────────────────────┐
128+
│ BUSINESS LAYER │
129+
│ ┌─────────────────────────────────────────────────────┐ │
130+
│ │ DATA PROTOCOL (8 specs) │ │
131+
│ │ Objects, Fields, Queries, Validations, Hooks │ │
132+
│ └─────────────────────────────────────────────────────┘ │
133+
└─────────────────────────────────────────────────────────────┘
134+
▼
135+
┌─────────────────────────────────────────────────────────────┐
136+
│ INFRASTRUCTURE LAYER │
137+
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
138+
│ │ SYSTEM │ │ API │ │ AUTH │ │PERMISSION│ │
139+
│ │(14 specs)│ │(6 specs) │ │(6 specs) │ │(4 specs) │ │
140+
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
141+
│ ┌─────────────────────────────────────────────────────┐ │
142+
│ │ SHARED PROTOCOL (1 spec) │ │
143+
│ │ Common Utilities & Identifiers │ │
144+
│ └─────────────────────────────────────────────────────┘ │
145+
└─────────────────────────────────────────────────────────────┘
146+
```
147+
148+
## Protocol Dependencies
149+
150+
```
151+
Stack Protocol
152+
▼
153+
┌─────────┴─────────┐
154+
▼ ▼
155+
Data Protocol UI Protocol
156+
│ │
157+
├─── Fields ────────┤
158+
├─── Objects ───────┤
159+
└─── Queries │
160+
│
161+
┌───────────────────┘
162+
▼
163+
Automation Protocol
164+
│
165+
├─── Flows ─────────┐
166+
├─── Workflows │
167+
└─── Approvals │
168+
▼
169+
System Protocol
170+
│
171+
┌──────────────┼──────────────┐
172+
▼ ▼ ▼
173+
Auth Protocol API Protocol Permission Protocol
174+
│
175+
┌─────┴─────┐
176+
▼ ▼
177+
Sharing RLS
178+
```
179+
180+
## Module Relationships
181+
182+
| Consumer Module | Depends On | Relationship |
183+
| :--- | :--- | :--- |
184+
| **Stack** | All modules | Aggregates entire system |
185+
| **UI** | Data, System, Auth | Renders data with security context |
186+
| **Automation** | Data, System, AI | Orchestrates business logic |
187+
| **AI** | Data, System | Enhances data with intelligence |
188+
| **API** | Data, Auth, Permission | Exposes data with security |
189+
| **Permission** | Data, Auth | Controls data access |
190+
| **Hub** | System, Auth | Multi-tenant packaging |
191+
| **Auth** | System | Identity foundation |
192+
| **Data** | Shared | Core business model |
193+
| **System** | Shared | Platform foundation |
194+
195+
## File Naming Conventions
196+
197+
All protocol files follow this pattern:
198+
199+
```
200+
<module>/<feature>.zod.ts
201+
```
202+
203+
Examples:
204+
- `data/field.zod.ts` → Field protocol
205+
- `ui/view.zod.ts` → View protocol
206+
- `system/manifest.zod.ts` → Manifest protocol
207+
- `ai/agent.zod.ts` → AI agent protocol
208+
209+
## Schema Naming Conventions
210+
211+
Within each `.zod.ts` file:
212+
213+
```typescript
214+
// Primary schema (PascalCase + "Schema" suffix)
215+
export const FieldSchema = z.object({ ... });
216+
217+
// Derived TypeScript type (inferred from Zod)
218+
export type Field = z.infer<typeof FieldSchema>;
219+
220+
// Supporting schemas
221+
export const SelectOptionSchema = z.object({ ... });
222+
export const VectorConfigSchema = z.object({ ... });
223+
```
224+
225+
## Quick Navigation
226+
227+
| Need | File | Location |
228+
| :--- | :--- | :--- |
229+
| Define an object/table | `object.zod.ts` | `packages/spec/src/data/` |
230+
| Define a field | `field.zod.ts` | `packages/spec/src/data/` |
231+
| Create a view | `view.zod.ts` | `packages/spec/src/ui/` |
232+
| Configure a dashboard | `dashboard.zod.ts` | `packages/spec/src/ui/` |
233+
| Build a workflow | `flow.zod.ts` | `packages/spec/src/automation/` |
234+
| Set up permissions | `permission.zod.ts` | `packages/spec/src/permission/` |
235+
| Add authentication | `identity.zod.ts` | `packages/spec/src/auth/` |
236+
| Create an AI agent | `agent.zod.ts` | `packages/spec/src/ai/` |
237+
| Configure a plugin | `manifest.zod.ts` | `packages/spec/src/system/` |
238+
| Define an API endpoint | `endpoint.zod.ts` | `packages/spec/src/api/` |
239+
240+
## See Also
241+
242+
- **[PROTOCOL_REFERENCE.md](./PROTOCOL_REFERENCE.md)** - Complete protocol inventory with detailed descriptions
243+
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System architecture overview
244+
- **[README.md](./README.md)** - Project overview and getting started
245+
- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Contributing guidelines

‎PROTOCOL_REFERENCE.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
55
Last Updated: 2026-01-27
66

7+
**📖 See also:** [PROTOCOL_ORGANIZATION.md](./PROTOCOL_ORGANIZATION.md) for visual diagrams and protocol relationships.
8+
79
## Overview
810

911
This document provides a comprehensive reference to all 70 protocol specifications that define the ObjectStack platform. Each protocol is implemented as a Zod schema (`.zod.ts` file) providing runtime validation and TypeScript type safety.

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ We've completed all advanced query features and AI/ML field types:
2626

2727
### Protocol Reference
2828
* **[Protocol Reference](./PROTOCOL_REFERENCE.md):** 📖 **Complete inventory of all 70 protocol specifications** with detailed descriptions, usage examples, and organization by module
29+
* **[Protocol Organization](./PROTOCOL_ORGANIZATION.md):** 🗺️ **Visual diagrams and maps** showing protocol structure, dependencies, and relationships
2930

3031
### Quick Start
3132
* **[Getting Started](./content/docs/guides/getting-started.mdx):** Quick introduction to ObjectStack Protocol

0 commit comments

Comments
 (0)