Skip to content

Commit 5ae6fe1

Browse files
hotlonghotlong
committed
Add tutorials section and architecture explanation
Introduces a new 'Tutorials' section with beginner, intermediate, and advanced guides, including task manager, micro-CRM, and federation examples. Adds an architecture explanation ('Why ObjectQL?'), updates navigation and sidebar in VitePress config, and enhances the homepage with protocol examples. These changes restructure documentation for better onboarding and clarity following the Diataxis framework.
1 parent 294a1b1 commit 5ae6fe1

File tree

8 files changed

+558
-0
lines changed

8 files changed

+558
-0
lines changed

‎DOCUMENTATION_PLAN.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Documentation Optimization Plan
2+
3+
## 🎯 Goal
4+
Restructure the documentation to follow the **Diataxis Framework** (Tutorials, Guides, Reference, Explanation) to make it more accessible and attractive to new developers.
5+
6+
## 🏗 Structural Changes
7+
8+
### 1. New Top-Level Section: `Tutorials` (Learning-oriented)
9+
Essential for onboarding. `Quick Start` is good, but developers need a "Step-by-Step" journey.
10+
- **Location**: `docs/tutorials/`
11+
- **Content**:
12+
- `build-your-first-app.md`: A complete Todo List or Blog implementation.
13+
- `building-crm.md`: Handling relationships and permissions.
14+
15+
### 2. Refine `Guide` -> `How-to Guides` (Task-oriented)
16+
Focus on solving specific problems.
17+
- Move "Core Fundamentals" to focus on *tasks* (e.g., "How to define a schema", "How to query specific fields").
18+
- Rename broad titles to actionable ones.
19+
20+
### 3. Highlight `Concepts` (Understanding-oriented)
21+
Create a clear distinction between "How do I do X?" and "How does X work?".
22+
- **New Section in Guide**: `Architecture & Concepts`
23+
- `why-objectql.md`: Deep dive into the "Why".
24+
- `federation-architecture.md`: Visual diagrams of how federation works.
25+
26+
### 4. Optimize Homepage (`docs/index.md`)
27+
- Add a "Code Block" Hero section: Show YAML Input -> SQL/API Output immediately.
28+
- Add "Use Cases" section.
29+
30+
## 📅 Execution Steps
31+
32+
### Step 1: Add Tutorials Section
33+
- [x] Create directory `docs/tutorials`
34+
- [x] Create `docs/tutorials/index.md` placeholder
35+
- [x] Update `docs/.vitepress/config.mts` to include "Tutorials" in Nav and Sidebar.
36+
37+
### Step 2: Content Injection
38+
- [ ] Write `build-your-first-app.md` content.
39+
40+
### Step 3: Visual Polish
41+
- [ ] Add diagrams to `guide/architecture.md`.

‎docs/.vitepress/config.mts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ export default defineConfig({
1414
logo: '/logo.svg',
1515
// Top Navigation
1616
nav: [
17+
{ text: 'Tutorials', link: '/tutorials/' },
1718
{ text: 'Guide', link: '/guide/' },
1819
{ text: 'AI-Native', link: '/ai/' },
1920
{ text: 'Protocol', link: '/spec/' },
@@ -22,6 +23,19 @@ export default defineConfig({
2223

2324
// Sidebar Configuration
2425
sidebar: {
26+
// Sidebar for Tutorials
27+
'/tutorials/': [
28+
{
29+
text: 'Tutorials',
30+
items: [
31+
{ text: 'Overview', link: '/tutorials/' },
32+
{ text: '1. Task Manager (Beginner)', link: '/tutorials/task-manager' },
33+
{ text: '2. Micro-CRM (Intermediate)', link: '/tutorials/crm-system' },
34+
{ text: '3. Federated Data (Advanced)', link: '/tutorials/federation' },
35+
]
36+
}
37+
],
38+
2539
// Sidebar for API section
2640
'/api/': [
2741
{
@@ -53,6 +67,7 @@ export default defineConfig({
5367
text: 'Start Here',
5468
items: [
5569
{ text: 'Introduction', link: '/guide/' },
70+
{ text: 'Why ObjectQL?', link: '/guide/architecture/why-objectql' },
5671
{ text: 'Quick Start', link: '/guide/getting-started' },
5772
{ text: '🤖 AI Coding Setup', link: '/ai/coding-assistant' },
5873
]

‎docs/guide/architecture/why-objectql.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Why ObjectQL?
2+
3+
In the era of AI automation, the requirements for backend infrastructure have shifted. We are no longer just building for human users on web forms; we are building systems that **AI Agents** need to read, understand, and manipulate.
4+
5+
## The Problem with Traditional ORMs
6+
7+
Tools like TypeORM, Prisma, or Sequelize are fantastic for human developers. They rely heavily on:
8+
1. **Complex TypeScript Types**: Great for IDE autocomplete, but invisible to an LLM running in a production execution environment.
9+
2. **Chained Method Calls**: `db.users.where(...).include(...)`. This requires the AI to synthesize valid executable code, which is prone to syntax errors and hallucinations.
10+
3. **Code-First Schema**: The schema is buried in class definitions, making it hard to extract a simple "map" of the data for the AI context window.
11+
12+
## The ObjectQL Solution: Protocol-First
13+
14+
ObjectQL treats **Logic as Data**.
15+
16+
### 1. Schema is JSON (The Context)
17+
Instead of parsing TypeScript files, an AI Agent can simply read a JSON definition. This is the native tongue of LLMs.
18+
19+
```json
20+
{
21+
"name": "contact",
22+
"fields": { "email": { "type": "text", "required": true } }
23+
}
24+
```
25+
26+
This compact format fits perfectly in RAG (Retrieval-Augmented Generation) contexts.
27+
28+
### 2. Queries are ASTs (The Action)
29+
To fetch data, the AI doesn't need to write SQL or function code. It generates a JSON object (Abstract Syntax Tree).
30+
31+
```json
32+
{
33+
"op": "find",
34+
"from": "contact",
35+
"filters": [["email", "contains", "@gmail.com"]]
36+
}
37+
```
38+
* **Safe**: No SQL Injection possible. The Driver handles escaping.
39+
* **Deterministic**: It either parses or it fails. No subtle logic bugs from misplaced parentheses in code.
40+
* **Portability**: The same JSON runs on Mongo, Postgres, or a REST API.
41+
42+
## Comparison
43+
44+
| Feature | Traditional ORM | ObjectQL |
45+
| :--- | :--- | :--- |
46+
| **Schema Definition** | TypeScript Classes / Migration Files | JSON / YAML Metadata |
47+
| **Query Language** | Fluent API / Raw SQL | JSON AST |
48+
| **Runtime** | Node.js / Python Runtime | Universal Protocol (Any Language) |
49+
| **AI Friendliness** | Low (Requires Code Gen) | High (Requires JSON Gen) |
50+
| **Dynamic Fields** | Hard (Migration required) | Native (Metadata-driven) |
51+
52+
## Conclusion
53+
54+
If you are building a Copilot, an Autonomous Agent, or a Low-Code platform, ObjectQL provides the structured, safe, and descriptive layer that connects your LLM to your database.

‎docs/index.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,77 @@ features:
3131
details: Seamlessly aggregate data from local databases and remote microservices into a single unified graph. The "GraphQL Federation" for backend logic.
3232
---
3333

34+
## Protocol by Example
35+
36+
See how ObjectQL transforms abstract definitions into working software.
37+
38+
### 1. Logic & Filtering
39+
40+
::: code-group
41+
42+
```yaml [1. Input: account.object.yml]
43+
name: account
44+
fields:
45+
name: text
46+
industry: select
47+
revenue: currency
48+
status: select
49+
```
50+
51+
```bash [2. Request: Complex Query]
52+
{
53+
"fields": ["name", "revenue"],
54+
"filters": [
55+
["industry", "=", "tech"],
56+
"and",
57+
[["revenue", ">", 1000000], "or", ["status", "=", "vip"]]
58+
]
59+
}
60+
```
61+
62+
```sql [3. Output: Optimized SQL]
63+
SELECT name, revenue
64+
FROM account
65+
WHERE industry = 'tech'
66+
AND (revenue > 1000000 OR status = 'vip')
67+
LIMIT 20
68+
:::
69+
70+
### 2. Auto-Joins & Aggregations
71+
72+
ObjectQL automatically handles `JOIN` operations when you group by related fields.
73+
74+
::: code-group
75+
76+
```yaml [1. Input: payment.object.yml]
77+
name: payment
78+
fields:
79+
amount: currency
80+
account:
81+
type: lookup
82+
reference_to: account
83+
```
84+
85+
```json [2. Request: JSON Protocol]
86+
{
87+
"op": "aggregate",
88+
"from": "payment",
89+
"group": ["account.industry"],
90+
"sum": ["amount"]
91+
}
92+
```
93+
94+
```sql [3. Output: SQL Generation]
95+
SELECT t2.industry, SUM(t1.amount)
96+
FROM payment AS t1
97+
LEFT JOIN account AS t2 ON t1.account = t2.id
98+
GROUP BY t2.industry
99+
```
100+
101+
:::
102+
103+
## The Shift to AI Programming
104+
34105
## The Shift to AI Programming
35106

36107
We believe the future of software development isn't about humans writing better code—it's about **Humans architecting systems that AI can implement**.

‎docs/tutorials/crm-system.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Building a Micro-CRMSystem
2+
3+
> **Prerequisites**: Completed [Build Your First App](./task-manager).
4+
5+
In this tutorial, we will explore **Relationships**, **Validation**, and **Hooks** by building a minimal CRM (Customer Relationship Management) system.
6+
7+
## 1. Define the Objects
8+
9+
We need two objects: `account` (Companies) and `contact` (People).
10+
11+
Create `account.object.yml`:
12+
```yaml
13+
name: account
14+
label: Account
15+
fields:
16+
name:
17+
type: text
18+
required: true
19+
searchable: true
20+
industry:
21+
type: select
22+
options:
23+
- technology
24+
- finance
25+
- retail
26+
annual_revenue:
27+
type: currency
28+
owner:
29+
type: lookup
30+
reference_to: users
31+
```
32+
33+
Create `contact.object.yml`:
34+
```yaml
35+
name: contact
36+
label: Contact
37+
fields:
38+
first_name:
39+
type: text
40+
required: true
41+
last_name:
42+
type: text
43+
required: true
44+
email:
45+
type: text
46+
required: true
47+
account:
48+
type: lookup
49+
reference_to: account # <--- Relationship
50+
required: true
51+
```
52+
53+
## 2. Add Validation
54+
55+
We want to ensure that `annual_revenue` is never negative.
56+
57+
In `account.object.yml`, add a validation rule:
58+
59+
```yaml
60+
validation_rules:
61+
positive_revenue:
62+
expression: "annual_revenue >= 0"
63+
message: "Annual revenue cannot be negative"
64+
```
65+
66+
> **Note**: ObjectQL supports expression-based validation directly in the metadata.
67+
68+
## 3. Implement Business Logic (Hooks)
69+
70+
We want to automatically set the `full_name` of a contact whenever it is created or updated.
71+
72+
Create or update your server entry point (e.g., `index.ts`):
73+
74+
```typescript
75+
// ... app initialization ...
76+
77+
// Register a trigger
78+
app.on('beforeCreate', 'contact', async ({ data }) => {
79+
if (data) {
80+
data.full_name = `${data.first_name} ${data.last_name}`;
81+
}
82+
});
83+
84+
app.on('beforeUpdate', 'contact', async ({ data }) => {
85+
if (data && (data.first_name || data.last_name)) {
86+
// Note: In a real app, you might need to fetch the existing first/last name
87+
// if only one is being updated, but for simplicity:
88+
data.full_name = `${data.first_name} ${data.last_name}`;
89+
}
90+
});
91+
```
92+
93+
Don't forget to add the `full_name` field to `contact.object.yml`:
94+
```yaml
95+
full_name:
96+
type: text
97+
readonly: true # Prevent manual edits via API
98+
```
99+
100+
## 4. Query with Relationships
101+
102+
Now start your server and try querying contacts with their account details included.
103+
104+
**Request:**
105+
```bash
106+
curl -G http://localhost:3000/api/data/contact \
107+
--data-urlencode 'filters=[["email", "contains", "@example.com"]]' \
108+
--data-urlencode 'expand=["account"]'
109+
```
110+
111+
**ObjectQL automatically resolves the lookup:**
112+
113+
```json
114+
{
115+
"value": [
116+
{
117+
"_id": "contact_123",
118+
"first_name": "Alice",
119+
"full_name": "Alice Smith",
120+
"account": {
121+
"_id": "acc_456",
122+
"name": "Tech Corp",
123+
"industry": "technology"
124+
}
125+
}
126+
]
127+
}
128+
```
129+
130+
## Summary
131+
132+
You have just built a relational data system with business logic in minutes.
133+
- **Relationships**: Defined via `reference_to`.
134+
- **Validation**: Declarative rules in YAML.
135+
- **Logic**: TypeScript hooks for dynamic behavior.

0 commit comments

Comments
 (0)