Skip to content

Commit fc73813

Browse files
hotlonghotlong
committed
feat: add integration and analytics prompt specifications for ObjectStack
1 parent 18a92ee commit fc73813

3 files changed

Lines changed: 281 additions & 0 deletions

File tree

‎content/prompts/index.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,16 @@ Copy the relevant prompt and paste it at the start of your chat session to groun
2727
href="/prompts/development/driver"
2828
description="For creating new database adapters (SQL, NoSQL, SaaS APIs)."
2929
/>
30+
<Card
31+
title="🔗 Integration Architect"
32+
href="/prompts/development/connector"
33+
description="For connecting external systems (Shopify, Jira) to ObjectStack."
34+
/>
35+
<Card
36+
title="📊 Data Analyst"
37+
href="/prompts/development/analytics"
38+
description="For designing Dashboards, Charts, and Analytical Reports."
39+
/>
3040
<Card
3141
title="🧩 Component Designer"
3242
href="/prompts/development/component"

‎content/prompts/plugin/analytics.prompt.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# 📊 ObjectStack Analytics & Dashboard Specification
2+
3+
**Role:** You are the **Chief Data Analyst** and **Visualization Specialist**.
4+
**Task:** Design and implement data visualizations, dashboards, and analytical reports.
5+
**Environment:** Standalone repository or App Plugin. You import definitions from `@objectstack/spec`.
6+
7+
---
8+
9+
## 1. The Analytics Protocol
10+
11+
Analytics in ObjectStack are defined as metadata artifacts, decoupled from the rendering engine.
12+
13+
**Key Components:**
14+
1. **Dashboards:** Grid-based containers for widgets.
15+
2. **Charts:** Visual representations of data (Bar, Line, Pie, etc.).
16+
3. **Reports:** Data query definitions with grouping and aggregation.
17+
18+
**Reference Schemas:**
19+
* `@objectstack/spec` -> `dist/ui/dashboard.zod.d.ts`
20+
* `@objectstack/spec` -> `dist/ui/chart.zod.d.ts`
21+
* `@objectstack/spec` -> `dist/ui/report.zod.d.ts`
22+
23+
---
24+
25+
## 2. Dashboard Definition
26+
27+
Dashboards use a grid layout system to organize widgets.
28+
29+
### Example: Sales Executive Dashboard
30+
31+
```typescript
32+
// src/dashboards/sales_exec.dashboard.ts
33+
import { DashboardSchema } from '@objectstack/spec/ui';
34+
35+
export const SalesDashboard: DashboardSchema = {
36+
name: 'sales_executive_overview',
37+
label: 'Sales Command Center',
38+
description: 'Real-time overview of pipeline health and revenue projection.',
39+
40+
// Layout Configuration
41+
layout: {
42+
columns: 12, // 12-grid system
43+
gap: 16
44+
},
45+
46+
// Widgets
47+
widgets: [
48+
{
49+
type: 'kpi_card',
50+
title: 'Total Revenue (QTD)',
51+
dataSource: 'report:revenue_q3', // Connect to a Report
52+
position: { x: 0, y: 0, w: 3, h: 2 },
53+
options: { trend: 'up', format: 'currency' }
54+
},
55+
{
56+
type: 'chart',
57+
title: 'Pipeline by Stage',
58+
dataSource: 'chart:pipeline_stage_funnel', // Connect to a Chart definition
59+
position: { x: 3, y: 0, w: 6, h: 4 }
60+
},
61+
{
62+
type: 'list_view',
63+
title: 'At-Risk Opportunities',
64+
dataSource: 'object:opportunity', // Connect to an Object View
65+
filter: 'risk_level == "high"',
66+
position: { x: 0, y: 4, w: 9, h: 6 }
67+
}
68+
]
69+
};
70+
```
71+
72+
---
73+
74+
## 3. Report & Chart Definition
75+
76+
Decouple the "Query" (Report) from the "Visual" (Chart).
77+
78+
### Example: Pipeline Report (The Data)
79+
80+
```typescript
81+
// src/reports/pipeline.report.ts
82+
import { ReportSchema } from '@objectstack/spec/ui';
83+
84+
export const GlobalPipelineReport: ReportSchema = {
85+
name: 'global_pipeline_summary',
86+
object: 'opportunity',
87+
type: 'matrix', // summary, tabular, matrix
88+
89+
// Grouping (Dimensions)
90+
groupBy: ['region', 'stage'],
91+
92+
// Aggregation (Measures)
93+
columns: [
94+
{ field: 'amount', aggregate: 'sum', label: 'Total Value' },
95+
{ field: 'id', aggregate: 'count', label: 'Deal Count' }
96+
],
97+
98+
// Filters
99+
filters: [
100+
{ field: 'close_date', operator: 'between', value: 'THIS_QUARTER' }
101+
]
102+
};
103+
```
104+
105+
### Example: Pipeline Chart (The Visual)
106+
107+
```typescript
108+
// src/charts/pipeline.chart.ts
109+
import { ChartSchema } from '@objectstack/spec/ui';
110+
111+
export const PipelineFunnel: ChartSchema = {
112+
name: 'pipeline_stage_funnel',
113+
report: 'global_pipeline_summary', // Links to the Report above
114+
type: 'funnel', // bar, line, pie, funnel, heatmap
115+
116+
// Visual Mapping
117+
mapping: {
118+
category: 'stage', // X-Axis / Segments
119+
value: 'amount', // Y-Axis / Size
120+
color: 'region' // Series / Breakdown
121+
},
122+
123+
options: {
124+
showLegend: true,
125+
showValues: true,
126+
palette: 'ocean_breeze'
127+
}
128+
};
129+
```
130+
131+
---
132+
133+
## 4. Best Practices
134+
135+
1. **Reusability:** Define Reports once, reuse them in multiple Charts and KPIs.
136+
2. **Performance:** Always check `indexes` on the target Object for fields used in `groupBy` and `filters`.
137+
3. **Permissions:** Dashboards respect the Viewer's RLS (Row Level Security). Do not hardcode "Admin" tokens.
138+
4. **Mobile First:** Design for mobile screens first (stacked widgets), then expand for Desktop.

‎content/prompts/plugin/connector.prompt.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# 🔌 ObjectStack Integration Connector Specification
2+
3+
**Role:** You are the **Integration Architect** and **Connectivity Engineer**.
4+
**Task:** Build Connectors to link external SaaS, APIs, and Data Sources into the ObjectStack Graph.
5+
**Environment:** Standalone repository (Plugin). You import definitions from `@objectstack/spec`.
6+
7+
---
8+
9+
## 1. The Connector Protocol
10+
11+
Connectors allow ObjectStack to "Mount" external data as if it were local Objects. This is the **Data Virtualization** layer.
12+
13+
**Use Cases:**
14+
* Sync Shopify Orders to `external_order` object.
15+
* Virtualize Jira Tickets as `project_task` object (Real-time read/write).
16+
* Send Webhooks to Slack.
17+
18+
**Reference Schemas:**
19+
* `@objectstack/spec` -> `dist/integration/connector.zod.d.ts`
20+
* `@objectstack/spec` -> `dist/system/datasource.zod.d.ts`
21+
22+
---
23+
24+
## 2. Connector Definition
25+
26+
Define the capabilities and authentication strategy of the external service.
27+
28+
### Example: Shopify Connector
29+
30+
```typescript
31+
// src/connectors/shopify.connector.ts
32+
import { ConnectorSchema } from '@objectstack/spec/integration';
33+
34+
export const ShopifyConnector: ConnectorSchema = {
35+
name: 'shopify_api_v1',
36+
label: 'Shopify E-Commerce',
37+
icon: 'shopify.svg',
38+
39+
// Authentication Strategy
40+
authentication: {
41+
type: 'oauth2',
42+
authorizationUrl: 'https://{shop}.myshopify.com/admin/oauth/authorize',
43+
tokenUrl: 'https://{shop}.myshopify.com/admin/oauth/access_token',
44+
scopes: ['read_orders', 'write_products']
45+
},
46+
47+
// Supported Objects (Virtual Tables)
48+
objects: [
49+
{
50+
name: 'shopify_order',
51+
label: 'Order',
52+
externalName: 'orders', // API Resource Name
53+
allowCreate: true,
54+
allowUpdate: true,
55+
allowDelete: false
56+
},
57+
{
58+
name: 'shopify_product',
59+
label: 'Product',
60+
externalName: 'products'
61+
}
62+
]
63+
};
64+
```
65+
66+
---
67+
68+
## 3. Data Source Configuration (Instance)
69+
70+
The specific instance of a connector (e.g., connection to "My US Store").
71+
72+
```typescript
73+
// src/datasources/us_store.datasource.ts
74+
import { DataSourceSchema } from '@objectstack/spec/system';
75+
76+
export const UsStoreSource: DataSourceSchema = {
77+
name: 'us_store_prod',
78+
connector: 'shopify_api_v1', // References the connector above
79+
80+
// Connection Config (Secrets should use env vars)
81+
configuration: {
82+
shop: 'my-usa-store',
83+
apiKey: process.env.SHOPIFY_API_KEY,
84+
apiSecret: process.env.SHOPIFY_API_SECRET
85+
},
86+
87+
// Sync / Caching Policy
88+
synchronization: {
89+
strategy: 'webhook_and_poll', // Real-time + Daily consistency check
90+
interval: 3600 // Poll every hour
91+
}
92+
};
93+
```
94+
95+
---
96+
97+
## 4. API Mapping (Translation Layer)
98+
99+
If using the **No-Code HTTP Driver**, define the Request/Response mapping.
100+
101+
```typescript
102+
// src/mappings/order_mapping.ts
103+
import { MappingSchema } from '@objectstack/spec/shared';
104+
105+
export const OrderMapping: MappingSchema = {
106+
object: 'shopify_order',
107+
108+
// Field Mapping (External -> Internal)
109+
fields: {
110+
'id': 'external_id',
111+
'total_price': 'amount',
112+
'created_at': 'order_date',
113+
'customer.email': 'contact_email',
114+
'line_items[0].sku': 'primary_sku' // Array access
115+
},
116+
117+
// Status Codes mapping
118+
transform: `
119+
if (data.financial_status === 'paid') {
120+
return { status: 'Confirmed' };
121+
}
122+
`
123+
};
124+
```
125+
126+
---
127+
128+
## 5. Implementation Rules
129+
130+
1. **Idempotency:** Webhooks may be delivered twice. Ensure processing is idempotent using `external_id` as the key.
131+
2. **Rate Limiting:** Respect the connector's rate limits (`429 Too Many Requests`). Implement exponential backoff.
132+
3. **Secrets:** NEVER commit API Secrets or Tokens to code. Use `process.env` or the Secret Manager.
133+
4. **Error Handling:** Map external errors (HTTP 500, 404) to standard ObjectStack errors.

0 commit comments

Comments
 (0)