diff --git a/apps/site/content/docs/data-access/index.mdx b/apps/site/content/docs/data-access/index.mdx new file mode 100644 index 00000000..7c95dacb --- /dev/null +++ b/apps/site/content/docs/data-access/index.mdx @@ -0,0 +1,99 @@ +--- +title: Data Access +description: Learn how to query and access data using ObjectQL's type-safe SDK and JSON-based protocol +--- + +ObjectQL provides powerful data access capabilities through a **JSON-based Protocol** that works seamlessly across different database backends. Unlike SQL strings or Query Builders, ObjectQL queries are structured data that are type-safe, serializable, and perfect for AI agents. + +## Overview + +The data access layer in ObjectQL is designed to be: + +- **Type-Safe**: Full TypeScript support with auto-generated types from your schema +- **Database Agnostic**: The same query works on MongoDB, PostgreSQL, SQLite, and more +- **AI-Friendly**: Structured JSON format prevents hallucinations and syntax errors +- **Serializable**: Queries can be sent over HTTP, stored in files, or logged for debugging + +## Key Topics + +### [Querying Data](/docs/data-access/querying) + +Learn the fundamentals of querying data with ObjectQL: +- Find operations and filters +- Sorting and pagination +- Field selection and data expansion +- Aggregations and grouping +- Complex queries with nested conditions + +### [Client SDK](/docs/data-access/sdk) + +Use the TypeScript SDK for type-safe data access: +- Installation and setup +- Basic CRUD operations +- Advanced querying techniques +- Error handling +- TypeScript integration + +### [Query Best Practices](/docs/data-access/best-practices) + +Optimize your queries for performance: +- Query optimization strategies +- Avoiding N+1 problems +- Efficient data loading +- Caching strategies +- Performance benchmarks + +## Quick Example + +```typescript +import { ObjectQL } from '@objectql/core'; + +// Initialize ObjectQL +const app = new ObjectQL({ + datasources: { + default: driver + } +}); + +await app.init(); +const ctx = app.createContext({ isSystem: true }); + +// Query data with filters +const products = await ctx.object('product').find({ + fields: ['name', 'price', 'category'], + filters: [ + ['category', '=', 'electronics'], + 'and', + ['price', '<', 1000] + ], + sort: [['price', 'asc']], + top: 10 +}); + +console.log('Products:', products); +``` + +## JSON Query Protocol + +All queries in ObjectQL follow a consistent JSON structure: + +```json +{ + "op": "find", + "object": "product", + "args": { + "fields": ["name", "price"], + "filters": [["category", "=", "electronics"]], + "top": 10 + } +} +``` + +This structure makes it easy for frontends, AI agents, and external systems to generate safe, valid queries. + +## Next Steps + +- Start with **[Querying Data](/docs/data-access/querying)** to learn the basics +- Explore the **[Client SDK](/docs/data-access/sdk)** for type-safe access +- Review **[Best Practices](/docs/data-access/best-practices)** for optimization strategies +- Check the **[API Reference](/docs/reference/api)** for complete documentation diff --git a/apps/site/content/docs/server/index.mdx b/apps/site/content/docs/server/index.mdx new file mode 100644 index 00000000..d65eff95 --- /dev/null +++ b/apps/site/content/docs/server/index.mdx @@ -0,0 +1,147 @@ +--- +title: Server & Deployment +description: Learn how to configure, integrate, and deploy ObjectQL applications +--- + +ObjectQL is designed to be **framework-agnostic** and can be integrated with any Node.js server or deployed to various environments. This section covers server configuration, integration patterns, and deployment strategies. + +## Overview + +The server layer in ObjectQL provides: + +- **Multiple Framework Support**: Express, Next.js, Fastify, and more +- **API Styles**: REST, JSON-RPC, GraphQL, and WebSocket support +- **Configuration Management**: Environment-based configuration +- **Plugin System**: Extend functionality with plugins +- **Microservices**: Federation and distributed architectures + +## Key Topics + +### [Configuration](/docs/server/configuration) + +Configure your ObjectQL application: +- Database connections +- Environment variables +- Metadata loading +- Driver configuration +- Runtime options + +### [Server Integration](/docs/server/integration) + +Integrate ObjectQL with web frameworks: +- Express.js setup +- Next.js integration +- Fastify adapter +- Custom server setup +- HTTP API exposure + +### [Microservices & Federation](/docs/server/microservices) + +Build distributed systems with ObjectQL: +- Service federation +- Remote data sources +- Cross-service queries +- Load balancing +- Service discovery + +### [Plugin System](/docs/server/plugins) + +Extend ObjectQL with plugins: +- Creating custom plugins +- Plugin lifecycle +- Bundling behavior +- Sharing plugins +- Official plugins + +## Quick Setup + +### Express Integration + +```typescript +import express from 'express'; +import { ObjectQL } from '@objectql/core'; +import { SqlDriver } from '@objectql/driver-sql'; +import { createNodeHandler } from '@objectql/server'; + +const app = express(); + +// Initialize ObjectQL +const objectql = new ObjectQL({ + datasources: { + default: new SqlDriver({ + client: 'postgresql', + connection: process.env.DATABASE_URL + }) + } +}); + +await objectql.init(); + +// Mount ObjectQL handler +app.use('/api/objectql', createNodeHandler(objectql)); + +// Start server +app.listen(3000, () => { + console.log('Server running on http://localhost:3000'); +}); +``` + +### Configuration File + +```typescript +// objectql.config.ts +import { defineConfig } from '@objectql/core'; + +export default defineConfig({ + datasources: { + default: { + driver: 'sql', + client: 'postgresql', + connection: { + host: process.env.DB_HOST, + database: process.env.DB_NAME, + user: process.env.DB_USER, + password: process.env.DB_PASSWORD + } + } + }, + modules: [ + 'src/objects', + '@objectql/module-auth' + ] +}); +``` + +## Deployment Patterns + +### Traditional Server + +Deploy to VPS, EC2, or dedicated servers: +- Process management with PM2 +- Nginx reverse proxy +- Environment configuration +- Database migrations + +### Serverless + +Deploy to serverless platforms: +- AWS Lambda +- Vercel Functions +- Cloudflare Workers +- Database connection pooling + +### Containers + +Deploy with Docker: +- Dockerfile configuration +- Docker Compose setup +- Kubernetes deployment +- Health checks and monitoring + +## Next Steps + +- Configure your application with **[Configuration](/docs/server/configuration)** +- Integrate with your framework using **[Server Integration](/docs/server/integration)** +- Scale with **[Microservices](/docs/server/microservices)** +- Extend with the **[Plugin System](/docs/server/plugins)** +- Review **[API Reference](/docs/reference/api)** for complete documentation diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index ab7a535a..f10ad686 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -54,7 +54,9 @@ const guideSidebar = [ { text: 'Low-Code UI', items: [ - { text: 'Page & Layouts', link: '/guide/page-metadata' }, + { text: 'Pages & Layouts', link: '/spec/page' }, + { text: 'Views', link: '/spec/view' }, + { text: 'Forms', link: '/spec/form' }, ] }, { diff --git a/docs/IMPLEMENTATION_SUMMARY.md b/docs/IMPLEMENTATION_SUMMARY.md index e5b11770..6ad698c5 100644 --- a/docs/IMPLEMENTATION_SUMMARY.md +++ b/docs/IMPLEMENTATION_SUMMARY.md @@ -1,8 +1,6 @@ -# ObjectQL Attachment API - Implementation Summary +# Attachment API Implementation Summary -## Overview - -This implementation adds comprehensive file attachment functionality to ObjectQL, enabling seamless file upload, storage, and download capabilities through REST API endpoints. +Implementation documentation for ObjectQL's comprehensive file attachment system. This summary covers file storage abstraction, REST API endpoints, upload/download functionality, and integration with object metadata for seamless file management. ## What Has Been Implemented diff --git a/docs/METADATA_TYPES_IMPLEMENTATION.md b/docs/METADATA_TYPES_IMPLEMENTATION.md index 2f87b06f..18885d0d 100644 --- a/docs/METADATA_TYPES_IMPLEMENTATION.md +++ b/docs/METADATA_TYPES_IMPLEMENTATION.md @@ -1,8 +1,6 @@ -# Metadata Type Definitions - Implementation Summary +# Metadata Type Definitions Implementation -## Overview - -This PR implements complete TypeScript type definitions for all ObjectQL metadata formats. Previously, only some metadata types (Object, Validation, Permission, etc.) had TypeScript definitions. This implementation adds the missing types to achieve 100% coverage. +Complete TypeScript type definitions for all ObjectQL metadata formats. This implementation document covers the 100% type coverage achievement, including views, forms, pages, reports, menus, apps, actions, hooks, and workflows—ensuring full type safety across the metadata system. ## New Type Definitions Added diff --git a/docs/ai/building-apps.md b/docs/ai/building-apps.md index 2369bde9..a9995f11 100644 --- a/docs/ai/building-apps.md +++ b/docs/ai/building-apps.md @@ -1,6 +1,6 @@ -# Building AI-Native Apps +# Building AI-Native Applications -ObjectQL is engineered to be the ideal data layer for AI Agents and LLMs. By providing a **Structure-First** protocol (JSON AST) instead of raw strings (SQL), it drastically reduces hallucinations and injection risks. +Learn how to use ObjectQL as the data layer for AI applications. This comprehensive guide covers RAG (Retrieval-Augmented Generation), semantic search, vector databases, and building AI agents with structured data protocols. ## 1. Why ObjectQL for AI? diff --git a/docs/ai/cli-usage.md b/docs/ai/cli-usage.md index 6a7eb08c..b72505d3 100644 --- a/docs/ai/cli-usage.md +++ b/docs/ai/cli-usage.md @@ -1,6 +1,6 @@ -# AI-Powered CLI +# AI-Powered Command Line Interface -The ObjectQL CLI provides AI-powered commands to generate and validate applications using natural language. +Learn how to use ObjectQL's AI-powered CLI for generating applications, validating metadata, and getting interactive assistance through natural language commands powered by large language models. ## Overview diff --git a/docs/ai/coding-assistant.md b/docs/ai/coding-assistant.md index f78cda58..9463523b 100644 --- a/docs/ai/coding-assistant.md +++ b/docs/ai/coding-assistant.md @@ -1,8 +1,6 @@ -# AI Coding Assistant Guide +# AI Coding Assistant Configuration -One of the core design goals of ObjectQL is to be the **most LLM-friendly backend protocol**. - -If you are using **Cursor**, **GitHub Copilot Chat**, **Windsurf**, or **ChatGPT** for development, please copy the following **System Prompt** into your AI configuration or project rules (e.g., `.cursorrules`). +Learn how to configure AI coding assistants (GitHub Copilot, Cursor, Windsurf) to become ObjectQL experts. This guide provides specialized system prompts that teach LLMs the ObjectQL protocol and best practices. This allows the AI to accurately understand ObjectQL's syntax and best practices. ## How to Use Effectively diff --git a/docs/ai/generating-apps.md b/docs/ai/generating-apps.md index 97297f7a..6d5039fe 100644 --- a/docs/ai/generating-apps.md +++ b/docs/ai/generating-apps.md @@ -1,8 +1,6 @@ -# Generating Apps with AI +# Generating Applications with AI -Because ObjectQL applications are defined primarily by **Metadata** (YAML/JSON) rather than **Code** (Classes/Functions), LLMs can generate complete, working backends in a single pass. - -This is "Zero-Shot Microservice Generation". +Learn how to generate complete ObjectQL applications from natural language descriptions. This guide covers zero-shot microservice generation, prompt templates, and best practices for AI-powered app creation using LLMs. ## The Workflow diff --git a/docs/ai/index.md b/docs/ai/index.md index 5838134c..29dd33ea 100644 --- a/docs/ai/index.md +++ b/docs/ai/index.md @@ -1,9 +1,6 @@ # AI-Native Development -ObjectQL resides at the intersection of Data and Artificial Intelligence. It is designed to be "AI-Native" in two distinct ways: - -1. **For AI Agents**: It serves as the perfect structured memory system (Long-term Memory) and tool interface for AI agents. -2. **By AI Agents**: Its metadata-driven, protocol-first architecture makes it incredibly easy for LLMs to write valid code for it. +ObjectQL bridges Data and Artificial Intelligence with AI-native architecture designed for both AI agents (as a structured memory system and tool interface) and by AI agents (with metadata-driven, LLM-friendly code generation). ## Overview diff --git a/docs/ai/programmatic-api.md b/docs/ai/programmatic-api.md index f7753401..99f32ab3 100644 --- a/docs/ai/programmatic-api.md +++ b/docs/ai/programmatic-api.md @@ -1,6 +1,6 @@ -# Programmatic AI API +# Programmatic AI Agent API -The ObjectQL AI Agent provides a programmatic API for generating and validating applications in your Node.js code. +Learn how to use the ObjectQL AI Agent programmatically in your Node.js applications. This guide covers the TypeScript API for building custom development tools, web UIs, and automation with AI-powered generation and validation. ## Overview diff --git a/docs/api/attachments.md b/docs/api/attachments.md index aa2eaf71..eba5a9e4 100644 --- a/docs/api/attachments.md +++ b/docs/api/attachments.md @@ -1,6 +1,6 @@ -# Attachment API Specification +# File Attachments and Upload API -**Version:** 1.0.0 +Learn how to handle file uploads, attachments, and media in ObjectQL. This comprehensive specification covers attachment fields, upload endpoints, storage strategies, and file management best practices. This document specifies how to handle file uploads, image uploads, and attachment field types in ObjectQL APIs. @@ -1236,7 +1236,7 @@ Configure file storage behavior using environment variables: ## Related Documentation - [Object Definition Specification](../spec/object.md) - Field type definitions -- [API Reference](./README.md) - Complete API documentation +- [API Reference](./index.md) - Complete API documentation - [Validation Rules](../spec/validation.md) - File validation configuration - [Server Integration](../guide/server-integration.md) - Setting up file storage diff --git a/docs/api/authentication.md b/docs/api/authentication.md index 4e0c4c17..aac6e2b7 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -1,4 +1,6 @@ -# Authentication & Authorization +# Authentication and Authorization + +Learn how to secure your ObjectQL APIs with authentication and authorization. This guide covers authentication methods, JWT tokens, role-based access control (RBAC), and permission enforcement strategies. ## Authentication Methods diff --git a/docs/api/client-sdk.md b/docs/api/client-sdk.md index dc821bf4..4a5cdf16 100644 --- a/docs/api/client-sdk.md +++ b/docs/api/client-sdk.md @@ -1,6 +1,6 @@ -# Client SDK Usage Guide +# Client SDK Usage -This guide demonstrates how to use the ObjectQL TypeScript client SDK to interact with Data API and Metadata API from frontend applications. +Learn how to use the ObjectQL TypeScript client SDK for frontend applications. This comprehensive guide covers SDK installation, configuration, API calls, and type-safe data access from JavaScript/TypeScript clients. ## Installation diff --git a/docs/api/custom-routes.md b/docs/api/custom-routes.md index b646d843..554541ba 100644 --- a/docs/api/custom-routes.md +++ b/docs/api/custom-routes.md @@ -1,4 +1,6 @@ -# Custom API Routes Configuration +# Custom API Routes + +Learn how to configure custom API routes in ObjectQL. This guide covers route definitions, custom endpoints, middleware integration, and extending the default API with your own handlers. ## Overview diff --git a/docs/api/error-handling.md b/docs/api/error-handling.md index 90ccf1a3..e7ec990d 100644 --- a/docs/api/error-handling.md +++ b/docs/api/error-handling.md @@ -1,4 +1,6 @@ -# Error Handling +# Error Handling and Response Format + +Learn about ObjectQL's error handling system and unified response format. This guide covers error codes, response structures, validation errors, and best practices for handling failures gracefully. ## Error Response Format diff --git a/docs/api/examples.md b/docs/api/examples.md index c126274c..1339c27f 100644 --- a/docs/api/examples.md +++ b/docs/api/examples.md @@ -1,4 +1,6 @@ -# Examples +# API Examples + +Practical examples demonstrating common ObjectQL API patterns and use cases. Learn through real-world scenarios including user registration, authentication flows, data queries, and business logic integration. ## Example 1: User Registration Flow diff --git a/docs/api/graphql.md b/docs/api/graphql.md index 80ebcc4c..c42e3b0f 100644 --- a/docs/api/graphql.md +++ b/docs/api/graphql.md @@ -1,6 +1,6 @@ # GraphQL API -ObjectQL provides a **GraphQL interface** for flexible, efficient queries with complex multi-table relationships. GraphQL allows clients to request exactly the data they need in a single request, making it ideal for modern frontends with complex data requirements. +Learn how to use ObjectQL's GraphQL interface for flexible, efficient queries with complex relationships. Perfect for modern frontends that need to request exactly the data they need in a single request. ## Overview @@ -938,7 +938,7 @@ mutation DeleteUser($id: String!) { - [GraphQL Specification](https://spec.graphql.org/) - [ObjectQL Query Language](../spec/query-language.md) -- [REST API Documentation](./README.md#rest-style-api) +- [REST API Documentation](./index.md) - [Authentication Guide](./authentication.md) --- diff --git a/docs/api/index.md b/docs/api/index.md index c51cdcfa..beabea89 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -1,8 +1,6 @@ -# API Documentation +# API Reference -Welcome to the ObjectQL API Reference. - -ObjectQL provides a **unified query protocol** that can be exposed through multiple API styles. All styles share the same underlying metadata, validation rules, and permissions system. +Welcome to the ObjectQL API Reference. Learn about the unified query protocol that powers multiple API styles including JSON-RPC, REST, GraphQL, and Metadata APIs—all sharing the same validation, permissions, and type safety. ## Design Principles diff --git a/docs/api/json-rpc.md b/docs/api/json-rpc.md index b4cf4811..14916684 100644 --- a/docs/api/json-rpc.md +++ b/docs/api/json-rpc.md @@ -1,6 +1,6 @@ -# JSON-RPC Style API +# JSON-RPC API -The **primary ObjectQL API** is a JSON-RPC style protocol where all operations are sent to a single endpoint. +Learn how to use ObjectQL's primary JSON-RPC API where all operations are sent to a single unified endpoint. This protocol-first approach is ideal for microservices, AI agents, and universal clients. ## Base Endpoint diff --git a/docs/api/metadata.md b/docs/api/metadata.md index 334a4f12..e8e32e70 100644 --- a/docs/api/metadata.md +++ b/docs/api/metadata.md @@ -1,6 +1,6 @@ # Metadata API -The Metadata API provides runtime access to schema information, object definitions, and configuration. +Learn how to access schema information at runtime through the Metadata API. This guide covers schema discovery, object definitions, field information, and dynamic configuration access. ## Base Endpoint diff --git a/docs/api/quick-reference.md b/docs/api/quick-reference.md index f2e4681d..0abc7ef0 100644 --- a/docs/api/quick-reference.md +++ b/docs/api/quick-reference.md @@ -1,6 +1,6 @@ # API Quick Reference -This is a condensed reference for the most common ObjectQL API operations. +A condensed reference guide for the most common ObjectQL API operations. Perfect for quick lookups during development—includes code snippets for CRUD operations, queries, and common patterns. ## Base Endpoint @@ -484,10 +484,10 @@ GET /api/metadata/objects/orders/actions ## Next Steps -- [Complete API Reference](./README.md) +- [Complete API Reference](./index.md) - [Authentication Guide](./authentication.md) - [Query Language Spec](../spec/query-language.md) -- [Examples](./README.md#examples) +- [Examples](./examples.md) --- diff --git a/docs/api/rate-limiting.md b/docs/api/rate-limiting.md index 5399ba8d..2040625c 100644 --- a/docs/api/rate-limiting.md +++ b/docs/api/rate-limiting.md @@ -1,6 +1,6 @@ -# Rate Limiting +# Rate Limiting and Throttling -ObjectQL supports configurable rate limiting to prevent abuse. +Learn how to configure rate limiting to protect your ObjectQL APIs from abuse. This guide covers rate limit strategies, configuration options, and response headers for throttled requests. ## Default Limits diff --git a/docs/api/rest.md b/docs/api/rest.md index eac550ac..ab6310ea 100644 --- a/docs/api/rest.md +++ b/docs/api/rest.md @@ -1,6 +1,6 @@ -# REST-Style API +# REST API -For traditional REST clients, ObjectQL can expose a REST-style interface. +Learn how to use ObjectQL's REST-style API for traditional web and mobile applications. This guide covers RESTful endpoints, resource patterns, and HTTP conventions for accessing ObjectQL data. ## Endpoints diff --git a/docs/api/websocket.md b/docs/api/websocket.md index ad8852e6..eb253ef0 100644 --- a/docs/api/websocket.md +++ b/docs/api/websocket.md @@ -1,6 +1,6 @@ -# WebSocket API +# WebSocket API (Real-time Updates) -*(Planned Feature)* +Learn about ObjectQL's WebSocket API for real-time data updates, subscriptions, and live queries. **Note: This is a planned feature currently under development.** For real-time updates and live data synchronization. diff --git a/docs/contributing.md b/docs/contributing.md index 4b9c742f..86fecd85 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,6 +1,6 @@ -# Contributing to ObjectQL +# Contributing Guide -Thank you for your interest in contributing to ObjectQL! This guide will help you get started. +Learn how to contribute to ObjectQL. This comprehensive guide covers code of conduct, development workflow, contribution types, pull request process, coding standards, testing guidelines, and documentation requirements. --- @@ -189,7 +189,7 @@ Then create a pull request on GitHub. ### 🔌 New Drivers -See the [Driver Extensibility Guide](./docs/guide/drivers/extensibility.md) for detailed instructions. +See the [Driver Extensibility Guide](./guide/drivers/extensibility.md) for detailed instructions. Quick steps: 1. Create a new package in `packages/drivers/` @@ -437,8 +437,9 @@ Description of the function. ## See Also -- [Related Feature](./related-feature.md) -- [API Reference](/api/) +- [API Reference](./api/) +- [Guide Documentation](./guide/) +- [Specifications](./spec/) ```` --- diff --git a/docs/data-access.md b/docs/data-access.md new file mode 100644 index 00000000..023f1221 --- /dev/null +++ b/docs/data-access.md @@ -0,0 +1,30 @@ +# Data Access + +This page has been reorganized. Please visit: + +- **[Querying Data](/guide/querying)** - Learn how to query and access data using ObjectQL's JSON-based protocol +- **[Query Best Practices](/guide/query-best-practices)** - Performance optimization and query strategies +- **[API Reference](/api/)** - Complete API documentation for data access +- **[Query Language Specification](/spec/query-language)** - JSON-DSL query protocol specification + +## Quick Links + +### For Querying Data +See the [Querying Data Guide](/guide/querying) for: +- Find operations +- Filters and conditions +- Sorting and pagination +- Field selection +- Data expansion + +### For API Access +See the [API Reference](/api/) for: +- [JSON-RPC API](/api/json-rpc) +- [REST API](/api/rest) +- [GraphQL API](/api/graphql) +- [Metadata API](/api/metadata) + +### For Advanced Topics +- [Query Best Practices](/guide/query-best-practices) - Optimization strategies +- [Query Language Spec](/spec/query-language) - Complete protocol specification +- [Client SDK](/api/client-sdk) - TypeScript client for frontend apps diff --git a/docs/development-plan.md b/docs/development-plan.md index 94eee3df..6077a5ab 100644 --- a/docs/development-plan.md +++ b/docs/development-plan.md @@ -1,9 +1,6 @@ -# ObjectQL Development Plan +# Development Plan (Q1-Q2 2026) -**Document Version:** 1.0 -**Last Updated:** January 18, 2026 -**Planning Period:** Q1-Q2 2026 -**Status:** Active +Detailed 6-month development plan for ObjectQL covering foundation stabilization, enterprise features, and production readiness. This actionable plan includes phase breakdowns, resource allocation, and milestone tracking for achieving v3.1.0 and v3.2.0. --- @@ -399,7 +396,7 @@ We welcome community contributions in the following areas: - **Examples** - Sample applications - **Bug Fixes** - Issue resolution -See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. +See [Contributing Guide](./contributing.md) for guidelines. --- @@ -541,10 +538,10 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. ### Related Documents -- [ROADMAP.md](./ROADMAP.md) - Long-term vision and milestones -- [CONTRIBUTING.md](./CONTRIBUTING.md) - Contribution guidelines -- [ARCHITECTURE.md](./docs/guide/architecture/overview.md) - System architecture -- [CHANGELOG.md](./CHANGELOG.md) - Version history +- [Roadmap](./roadmap.md) - Long-term vision and milestones +- [Contributing Guide](./contributing.md) - Contribution guidelines +- [Architecture Overview](./guide/architecture/overview.md) - System architecture +- [GitHub Releases](https://github.com/objectstack-ai/objectql/releases) - Version history ### References diff --git a/docs/examples/README_CN.md b/docs/examples/README_CN.md index 011ed206..957797a7 100644 --- a/docs/examples/README_CN.md +++ b/docs/examples/README_CN.md @@ -1,8 +1,6 @@ -# 附件 API 实现文档 +# Attachment API Implementation Guide (Chinese) -## 概述 - -本次实现为 ObjectQL 添加了完整的文件上传、下载和管理功能。实现包括： +Complete documentation for ObjectQL's file attachment implementation. This guide covers file storage abstraction, multipart form data parsing, validation, REST API endpoints, and comprehensive testing examples for building file upload functionality. 1. **文件存储抽象层** - 支持本地文件系统和内存存储，可扩展支持 S3、OSS 等云存储 2. **多部分表单数据解析** - 原生支持 multipart/form-data 文件上传 diff --git a/docs/examples/attachment-association-guide-cn.md b/docs/examples/attachment-association-guide-cn.md index 7ad75e68..99507185 100644 --- a/docs/examples/attachment-association-guide-cn.md +++ b/docs/examples/attachment-association-guide-cn.md @@ -1,6 +1,6 @@ -# 附件如何与对象记录关联 +# Attachment Association Guide (Chinese) -本文档详细说明在 ObjectQL 中如何将文件附件与对象记录关联，包括两种主要方案和最佳实践。 +Detailed guide on associating file attachments with object records in ObjectQL. This Chinese document covers two main approaches (embedded attachments vs. independent attachment objects), comparison, practical examples, and best practices. ## 目录 diff --git a/docs/examples/file-upload-example.md b/docs/examples/file-upload-example.md index b8fb1999..7846cbdb 100644 --- a/docs/examples/file-upload-example.md +++ b/docs/examples/file-upload-example.md @@ -1,6 +1,6 @@ # File Upload Example -This example demonstrates how to use the ObjectQL file upload API. +Practical code example demonstrating how to use the ObjectQL file upload API. This example shows complete setup, initialization, and implementation of file upload functionality with ObjectQL server and local file storage. ## Setup diff --git a/docs/examples/multiple-file-upload-guide-cn.md b/docs/examples/multiple-file-upload-guide-cn.md index 8b17bc1a..e548bd7e 100644 --- a/docs/examples/multiple-file-upload-guide-cn.md +++ b/docs/examples/multiple-file-upload-guide-cn.md @@ -1,8 +1,6 @@ -# 附件字段多选功能说明 +# Multiple File Upload Guide (Chinese) -## 概述 - -ObjectQL 附件字段**完全支持多选功能**，允许在单个附件字段上传和存储多个文件。通过设置 `multiple: true` 属性即可启用。 +Complete guide for implementing multiple file upload functionality in ObjectQL attachment fields. This Chinese document covers enabling multi-select with `multiple: true`, field configuration, batch upload methods, CRUD operations, and complete product gallery examples. ## 字段定义 diff --git a/docs/examples/s3-integration-guide-cn.md b/docs/examples/s3-integration-guide-cn.md index 30c35e50..4372fee2 100644 --- a/docs/examples/s3-integration-guide-cn.md +++ b/docs/examples/s3-integration-guide-cn.md @@ -1,6 +1,6 @@ -# 如何使用 AWS S3 存储附件 +# AWS S3 Integration Guide (Chinese) -本指南详细说明如何将 ObjectQL 文件附件存储到 AWS S3，包括完整的实现代码和最佳实践。 +Comprehensive guide for integrating AWS S3 storage with ObjectQL file attachments. This document covers architecture design, implementation, configuration, usage examples, advanced features, and best practices for scalable cloud storage. ## 目录 diff --git a/docs/guide/architecture/overview.md b/docs/guide/architecture/overview.md index c6d750a8..7afbf21c 100644 --- a/docs/guide/architecture/overview.md +++ b/docs/guide/architecture/overview.md @@ -1,6 +1,6 @@ -# Architecture & Concepts +# Architecture Overview -ObjectQL is built with a modular architecture that separates the data definition (Metadata) from the execution engine (Driver). This design allows applications to run on different database stacks (SQL vs NoSQL) without changing the business logic. +Learn about ObjectQL's modular architecture and core concepts. This guide covers the metadata layer, core engine, driver abstraction, dependency graph, and key design principles that make ObjectQL a universal data protocol. ## High-Level Overview diff --git a/docs/guide/architecture/why-objectql.md b/docs/guide/architecture/why-objectql.md index d6af4b7a..028dbe5b 100644 --- a/docs/guide/architecture/why-objectql.md +++ b/docs/guide/architecture/why-objectql.md @@ -1,6 +1,6 @@ -# Why ObjectQL? +# Why Choose ObjectQL? -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. +Understand the architectural philosophy behind ObjectQL and why it's designed for the AI era. This guide explains the limitations of traditional ORMs and how ObjectQL's protocol-first approach solves modern backend challenges. ## The Problem with Traditional ORMs diff --git a/docs/guide/cli.md b/docs/guide/cli.md index 97267f4b..97304e85 100644 --- a/docs/guide/cli.md +++ b/docs/guide/cli.md @@ -1,6 +1,6 @@ -# CLI Guide +# Command Line Interface (CLI) -The ObjectQL CLI (`@objectql/cli`) is an essential tool for development, automating tasks like type generation and database migrations. +The ObjectQL CLI (`@objectql/cli`) is a powerful command-line tool for development, providing features for project scaffolding, type generation, database migrations, AI-powered app generation, and development server management. ## 1. Installation diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index 3af29208..9b84479d 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -1,6 +1,6 @@ -# Configuration +# Application Configuration -ObjectQL is configured by passing an `ObjectQLConfig` object to the constructor. +Learn how to configure ObjectQL applications through the `ObjectQLConfig` object, including database connections, metadata paths, and runtime options. ## Basic Layout diff --git a/docs/guide/data-modeling.md b/docs/guide/data-modeling.md index 39b36186..1ae49b4d 100644 --- a/docs/guide/data-modeling.md +++ b/docs/guide/data-modeling.md @@ -1,6 +1,6 @@ -# Data Modeling Guide +# Data Modeling -Data modeling in ObjectQL is **Metadata-First**. You define your application's schema using `*.object.yml` files (or JSON), and ObjectQL handles validation, database mapping, and type generation. +Learn how to define your application's data models using ObjectQL's **metadata-first** approach. This guide covers object definitions, field types, relationships, and best practices for schema design using `*.object.yml` files. ## 1. The Object Definition diff --git a/docs/guide/drivers/extensibility.md b/docs/guide/drivers/extensibility.md index fb9ba69f..65e554b2 100644 --- a/docs/guide/drivers/extensibility.md +++ b/docs/guide/drivers/extensibility.md @@ -1,6 +1,6 @@ -# Driver Extensibility Guide +# Driver Extensibility -ObjectQL is designed to support multiple database backends through its **Driver** abstraction layer. This guide explains how to extend ObjectQL with additional database types. +Learn how to extend ObjectQL with additional database backends. This guide covers the driver architecture, available official drivers, and how to integrate new data sources into ObjectQL's universal protocol. ## Current Official Drivers diff --git a/docs/guide/drivers/implementing-custom-driver.md b/docs/guide/drivers/implementing-custom-driver.md index 212d0135..e255e6e3 100644 --- a/docs/guide/drivers/implementing-custom-driver.md +++ b/docs/guide/drivers/implementing-custom-driver.md @@ -1,6 +1,6 @@ # Implementing a Custom Driver -This guide walks you through implementing a custom database driver for ObjectQL. By the end, you'll understand how to create a driver that seamlessly integrates with ObjectQL's universal data protocol. +Learn how to create custom database drivers for ObjectQL. This comprehensive guide walks through implementing the driver interface, handling queries, transactions, and seamlessly integrating with ObjectQL's universal data protocol. ## Table of Contents diff --git a/docs/guide/drivers/index.md b/docs/guide/drivers/index.md index 422be13f..67e1c5de 100644 --- a/docs/guide/drivers/index.md +++ b/docs/guide/drivers/index.md @@ -1,8 +1,6 @@ -# Database Drivers +# Database Drivers Overview -ObjectQL relies on **Drivers** to communicate with the underlying database. A driver is responsible for translating the ObjectQL specific query format (AST) into the native query language of the database (SQL, MongoDB Query, etc.). - -You can configure multiple drivers for different parts of your application, or use a single driver for everything. +Learn about ObjectQL's database driver system and how it enables universal data access. This guide covers available drivers, configuration options, and how drivers translate ObjectQL queries into database-specific operations. ## Available Drivers diff --git a/docs/guide/drivers/mongo.md b/docs/guide/drivers/mongo.md index 6e087137..5f0ad40d 100644 --- a/docs/guide/drivers/mongo.md +++ b/docs/guide/drivers/mongo.md @@ -1,6 +1,6 @@ # MongoDB Driver -The MongoDB driver allows ObjectQL to store data in a MongoDB database (version 4.0+). It takes advantage of MongoDB's document model to store JSON fields natively and flexible schemas. +Learn how to use ObjectQL with MongoDB databases. This guide covers installation, configuration, document model features, and MongoDB-specific capabilities for version 4.0 and above. ## Installation diff --git a/docs/guide/drivers/sql.md b/docs/guide/drivers/sql.md index 21d4260f..21782a62 100644 --- a/docs/guide/drivers/sql.md +++ b/docs/guide/drivers/sql.md @@ -1,6 +1,6 @@ -# SQL Driver (Knex) +# SQL Driver (PostgreSQL, MySQL, SQLite) -The SQL driver implementation is based on [Knex.js](https://knexjs.org/), a powerful SQL query builder. It supports all major SQL databases including PostgreSQL, MySQL, SQLite3, and SQL Server. +Learn how to use the SQL driver for relational databases. This guide covers installation, configuration, and features for PostgreSQL, MySQL, SQLite, and SQL Server using the Knex.js query builder. ## Installation diff --git a/docs/guide/formulas-and-rules-quick-ref.md b/docs/guide/formulas-and-rules-quick-ref.md index bd152a95..b87e0c29 100644 --- a/docs/guide/formulas-and-rules-quick-ref.md +++ b/docs/guide/formulas-and-rules-quick-ref.md @@ -1,6 +1,6 @@ -# Formulas & Rules Quick Reference +# Formulas and Rules Quick Reference -**Quick syntax reference for ObjectQL formulas and validation rules.** +Quick syntax reference for ObjectQL formulas and validation rules. A condensed cheat sheet for common patterns, operators, and functions. For complete documentation, see: - 📖 [English Guide](./formulas-and-rules.md) diff --git a/docs/guide/formulas-and-rules.md b/docs/guide/formulas-and-rules.md index f5da18dd..7a174f23 100644 --- a/docs/guide/formulas-and-rules.md +++ b/docs/guide/formulas-and-rules.md @@ -1,6 +1,6 @@ -# Formulas and Rules Syntax Guide +# Formulas and Validation Rules -This guide covers the complete syntax for formulas and validation rules in ObjectQL. Understanding these patterns will help you create powerful calculated fields and enforce business rules. +Learn the complete syntax for creating formula fields and validation rules in ObjectQL. This comprehensive guide covers expressions, operators, functions, and patterns for building calculated fields and enforcing business logic. ## Table of Contents diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 3feddd08..15eb3b0e 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -1,6 +1,6 @@ -# Getting Started with ObjectQL +# Quick Start Guide -**ObjectQL** is a universal, metadata-driven ORM designed for building dynamic business applications. Unlike traditional ORMs where you define schema in class files (like TypeORM entities), ObjectQL uses a **Metadata-First** approach. +Learn how to get started with ObjectQL—a universal, metadata-driven ORM for building dynamic business applications. This guide covers project setup, schema definition, and your first steps with ObjectQL's metadata-first approach. ## Why ObjectQL? diff --git a/docs/guide/ide-setup.md b/docs/guide/ide-setup.md index ed7a0a1d..b3419631 100644 --- a/docs/guide/ide-setup.md +++ b/docs/guide/ide-setup.md @@ -1,6 +1,6 @@ -# IDE Setup +# IDE Setup and Development Tools -To get the best experience developing with ObjectQL, we recommend **Visual Studio Code** equipped with the official toolset. This setup provides you with an "AI-like" development experience with intelligent auto-completion, real-time validation, and instant code generation. +Learn how to configure your development environment for ObjectQL. This guide covers Visual Studio Code setup, official extensions, IntelliSense configuration, and tooling for an optimal development experience. ## Visual Studio Code Extension diff --git a/docs/guide/index.md b/docs/guide/index.md index 91e5d110..e4d7ddcc 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -1,6 +1,6 @@ -# Introduction +# Getting Started Guide -**ObjectQL** is a protocol-first application engine. It rethinks backend development by treating everything—Data Models, Queries, and Logic—as **structured data** rather than code strings. +Learn the fundamentals of ObjectQL—a protocol-first application engine that treats data models, queries, and logic as **structured data** rather than code strings. This guide introduces core philosophy, key concepts, and next steps. ## The Core Philosophy diff --git a/docs/guide/license.md b/docs/guide/license.md index de394337..5f2c0ab6 100644 --- a/docs/guide/license.md +++ b/docs/guide/license.md @@ -1,6 +1,6 @@ -# License +# License Information -ObjectQL is released under the **MIT License**. +ObjectQL is released under the **MIT License**. Learn about usage rights, attribution requirements, and how you can use ObjectQL in your projects. ## About This License diff --git a/docs/guide/logic-actions.md b/docs/guide/logic-actions.md index 9ed768be..81da43fc 100644 --- a/docs/guide/logic-actions.md +++ b/docs/guide/logic-actions.md @@ -1,6 +1,6 @@ -# Logic: Actions (RPC) +# Actions (Custom Server Functions) -Actions (Remote Procedure Calls) allow you to define custom backend functions that go beyond simple CRUD. They are integrated into the metadata, meaning the Frontend knows exactly how to render them (buttons, confirmation dialogs, forms) and the Backend knows how to validate them. +Learn how to define custom server-side functions using Actions (Remote Procedure Calls). Actions extend your application beyond CRUD operations, enabling complex business logic, integrations, and workflows with full metadata integration. ## 1. What is an Action? diff --git a/docs/guide/logic-hooks.md b/docs/guide/logic-hooks.md index c9108029..5e33bfe6 100644 --- a/docs/guide/logic-hooks.md +++ b/docs/guide/logic-hooks.md @@ -1,6 +1,6 @@ -# Logic Hooks +# Hooks (Database Triggers) -Hooks (often called "Triggers" in SQL databases) allow you to intercept database operations to inject custom logic. They are transaction-aware and fully typed. +Learn how to implement database hooks (triggers) to intercept and customize data operations. This guide covers before/after hooks, validation logic, side effects, and transaction-aware business rules. ## 1. Registration Methods diff --git a/docs/guide/metadata-organization.md b/docs/guide/metadata-organization.md index c7a53a97..ef748936 100644 --- a/docs/guide/metadata-organization.md +++ b/docs/guide/metadata-organization.md @@ -1,6 +1,6 @@ -# Organizing Metadata for Large Projects +# Metadata Organization and Project Structure -When building enterprise-scale applications with ObjectQL, proper metadata organization becomes critical. This guide demonstrates best practices for structuring your object definitions, actions, hooks, and translations in a maintainable way. +Learn best practices for organizing metadata in large-scale ObjectQL applications. This guide covers folder structures, file naming conventions, module organization, and strategies for maintaining complex enterprise projects. ## The Challenge diff --git a/docs/guide/microservices.md b/docs/guide/microservices.md index a4a8f112..0fb207f3 100644 --- a/docs/guide/microservices.md +++ b/docs/guide/microservices.md @@ -1,6 +1,6 @@ -# Microservices & Federation +# Microservices and Data Federation -ObjectQL provides a built-in mechanism to aggregate data from multiple services into a single unified graph. This is similar to **GraphQL Federation** or Salesforce's **External Objects**, but strictly for the ObjectQL protocol. +Learn how to build distributed systems with ObjectQL's federation capabilities. This guide covers connecting multiple services, remote data sources, and aggregating distributed data into a unified graph. ## Concept: Remote Remotes diff --git a/docs/guide/migration-id-field.md b/docs/guide/migration-id-field.md index e0378d7f..dbef5ff4 100644 --- a/docs/guide/migration-id-field.md +++ b/docs/guide/migration-id-field.md @@ -1,6 +1,6 @@ # Migration Guide: Unified ID Field -This guide helps you migrate from the legacy `_id` field to the unified `id` field API. +Learn how to migrate from the legacy `_id` field to the unified `id` field API. This guide provides step-by-step instructions, code examples, and migration strategies for updating existing applications. ## What Changed? diff --git a/docs/guide/plugins.md b/docs/guide/plugins.md index ab5aede2..ead5c7c6 100644 --- a/docs/guide/plugins.md +++ b/docs/guide/plugins.md @@ -1,6 +1,6 @@ # Plugin System -Plugins are the primary way to extend ObjectQL. They allow you to bundle behavior, schema modifications, and logic (hooks/actions) into reusable units. +Learn how to extend ObjectQL with plugins. This guide covers creating, registering, and distributing reusable plugins that bundle custom behavior, schema modifications, hooks, and actions. ## 1. Anatomy of a Plugin diff --git a/docs/guide/query-best-practices.md b/docs/guide/query-best-practices.md index 3b57cfbd..21ad9c86 100644 --- a/docs/guide/query-best-practices.md +++ b/docs/guide/query-best-practices.md @@ -1,6 +1,6 @@ -# Query Best Practices +# Query Best Practices and Performance Optimization -This guide provides best practices, performance optimization strategies, and recommendations for querying data in ObjectQL across different query interfaces (JSON-DSL, REST, GraphQL). +Learn best practices for querying data efficiently in ObjectQL. This comprehensive guide covers performance optimization strategies, choosing the right API style (JSON-DSL, REST, GraphQL), and benchmarks for different query patterns. --- diff --git a/docs/guide/querying.md b/docs/guide/querying.md index d55a9b86..33aec644 100644 --- a/docs/guide/querying.md +++ b/docs/guide/querying.md @@ -1,6 +1,6 @@ # Querying Data -ObjectQL uses a **JSON-based Protocol** for all data operations. Unlike SQL (strings) or Query Builders (chained methods), ObjectQL queries are **Data Structures**. +Learn how to query data using ObjectQL's **JSON-based protocol**. This guide covers the find operation, filters, sorting, pagination, field selection, and data expansion for building complex queries as structured data. This design makes it strictly typed, easy to serialise/transport over HTTP, and safe from injection—perfect for both human developers and AI Agents. diff --git a/docs/guide/server-integration.md b/docs/guide/server-integration.md index c017eeba..8d2b3c35 100644 --- a/docs/guide/server-integration.md +++ b/docs/guide/server-integration.md @@ -1,6 +1,6 @@ -# Server Integration +# Server Integration and HTTP APIs -ObjectQL is designed to be framework-agnostic. While it can be used directly as a library, we provide a standard `@objectql/server` package to expose your application via HTTP. +Learn how to integrate ObjectQL with web servers and frameworks. This guide covers the `@objectql/server` package, Express integration, Next.js setup, and exposing your application via REST, JSON-RPC, and GraphQL APIs. ## The `@objectql/server` Package diff --git a/docs/planning.md b/docs/planning.md index 3f7fd476..c2ebb4d3 100644 --- a/docs/planning.md +++ b/docs/planning.md @@ -1,6 +1,6 @@ -# Project Planning & Status +# Project Planning Hub -Welcome to the ObjectQL project planning hub. This section contains all strategic planning documents, development roadmaps, and current project status information. +Central hub for ObjectQL strategic planning documents. This section provides access to roadmaps, development plans, project status reports, and planning resources for understanding ObjectQL's direction and progress. --- diff --git a/docs/project-status.md b/docs/project-status.md index 74a9f81e..f873c07b 100644 --- a/docs/project-status.md +++ b/docs/project-status.md @@ -1,9 +1,6 @@ -# Project Status +# Project Status Report -**Project:** ObjectQL -**Version:** 3.0.0 -**Last Updated:** January 18, 2026 -**Status:** Active Development +Comprehensive status report for all ObjectQL ecosystem components. This document tracks package versions, test coverage, production readiness, and current development status across foundation, drivers, runtime, and tools layers. --- @@ -245,7 +242,7 @@ ObjectQL is a universal data compiler that transforms declarative YAML metadata - [ ] Complete audit system - [ ] Performance optimization -See [ROADMAP.md](./ROADMAP.md) for complete roadmap. +See [Roadmap](./roadmap.md) for complete roadmap. --- @@ -353,16 +350,16 @@ See [ROADMAP.md](./ROADMAP.md) for complete roadmap. We welcome contributions! See: -- [CONTRIBUTING.md](./CONTRIBUTING.md) - Contribution guidelines -- [DEVELOPMENT_PLAN.md](./DEVELOPMENT_PLAN.md) - Detailed development plan +- [Contributing Guide](./contributing.md) - Contribution guidelines +- [Development Plan](./development-plan.md) - Detailed development plan - [GitHub Issues](https://github.com/objectstack-ai/objectql/issues) - Open issues --- ## License -ObjectQL is released under the PolyForm Shield License 1.0.0. See [LICENSE](./LICENSE) for details. +ObjectQL is released under the PolyForm Shield License 1.0.0. See [LICENSE](../LICENSE) for details. --- -*This status document is updated monthly. For real-time updates, see the [CHANGELOG.md](./CHANGELOG.md) and [GitHub Releases](https://github.com/objectstack-ai/objectql/releases).* +*This status document is updated monthly. For real-time updates, see [GitHub Releases](https://github.com/objectstack-ai/objectql/releases).* diff --git a/docs/roadmap.md b/docs/roadmap.md index 69abd954..87a37a92 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,8 +1,6 @@ -# ObjectQL Roadmap +# ObjectQL Development Roadmap -**Last Updated:** January 2026 -**Current Version:** 3.0.0 -**Project Status:** Active Development +Learn about ObjectQL's vision, mission, and development roadmap. This document outlines current features, planned enhancements, and the strategic direction for making ObjectQL the standard protocol for AI software generation. --- @@ -305,7 +303,7 @@ ObjectQL aims to be the **Standard Protocol for AI Software Generation** - a uni This roadmap represents the core team's priorities, but we welcome community input: 1. **Feature Requests** - Open an issue with the `enhancement` label -2. **Driver Contributions** - See [Driver Extensibility Guide](./docs/guide/drivers/extensibility.md) +2. **Driver Contributions** - See [Driver Extensibility Guide](./guide/drivers/extensibility.md) 3. **Documentation** - Submit PRs to improve guides and examples 4. **Testing** - Help increase test coverage and report bugs diff --git a/docs/schema-introspection.md b/docs/schema-introspection.md index eea8650b..770cf693 100644 --- a/docs/schema-introspection.md +++ b/docs/schema-introspection.md @@ -1,6 +1,6 @@ -# Schema Introspection - Connect to Existing Databases +# Schema Introspection for Existing Databases -ObjectQL now supports **automatic schema introspection**, allowing you to connect to an existing database without defining any metadata. The system will automatically discover tables, columns, data types, and relationships. +Learn how to use automatic schema introspection to connect ObjectQL to existing databases. This feature discovers tables, columns, data types, and relationships without requiring metadata definitions—perfect for integrating with legacy systems. ## Features @@ -260,9 +260,88 @@ Convert introspected schema to ObjectQL object configurations. **Returns:** `ObjectConfig[]` - Array of object configurations -## Examples +## Complete Example -See [examples/connect-existing-database.ts](../examples/connect-existing-database.ts) for a complete working example. +Here's a complete working example with error handling and best practices: + +```typescript +import { ObjectQL } from '@objectql/core'; +import { SqlDriver } from '@objectql/driver-sql'; +import * as fs from 'fs'; +import * as path from 'path'; +import * as yaml from 'js-yaml'; + +async function connectExistingDatabase() { + try { + // Create driver for existing database + const driver = new SqlDriver({ + client: 'postgresql', + connection: { + host: process.env.DB_HOST || 'localhost', + database: process.env.DB_NAME || 'my_existing_db', + user: process.env.DB_USER || 'username', + password: process.env.DB_PASSWORD || 'password' + } + }); + + // Initialize ObjectQL + const app = new ObjectQL({ + datasources: { default: driver } + }); + + console.log('Connecting to database...'); + + // Introspect and register all tables + const objects = await app.introspectAndRegister('default', { + excludeTables: ['migrations', 'schema_version'] + }); + + console.log(`✅ Discovered ${objects.length} tables`); + + // Initialize and use + await app.init(); + const ctx = app.createContext({ isSystem: true }); + + // Query existing data + const users = await ctx.object('users').find({ + top: 10 + }); + + console.log(`Found ${users.length} users`); + + // Optionally export metadata to files + const outputDir = 'src/objects'; + + // Ensure directory exists + if (!fs.existsSync(outputDir)) { + fs.mkdirSync(outputDir, { recursive: true }); + } + + objects.forEach(obj => { + const filePath = path.join(outputDir, `${obj.name}.object.yml`); + try { + fs.writeFileSync(filePath, yaml.dump(obj)); + console.log(`✅ Exported ${obj.name} to ${filePath}`); + } catch (err) { + console.error(`❌ Failed to export ${obj.name}:`, err.message); + } + }); + + console.log('✅ Database connection successful!'); + + } catch (error) { + console.error('❌ Error connecting to database:', error.message); + if (error.code === 'ECONNREFUSED') { + console.error('Make sure the database server is running'); + } else if (error.code === '28P01') { + console.error('Authentication failed - check username and password'); + } + process.exit(1); + } +} + +connectExistingDatabase(); +``` ## Chinese Documentation (中文文档) diff --git a/docs/schema-migration-instructions.md b/docs/schema-migration-instructions.md index 8de7d53a..bd7e424f 100644 --- a/docs/schema-migration-instructions.md +++ b/docs/schema-migration-instructions.md @@ -1,10 +1,6 @@ -# Schema Migration Instructions - Implementation Summary +# Schema Migration Instructions - Implementation Reference -## Problem Statement - -**如何表达对象和字段的更新与删除指令** (How to express object and field update and delete instructions) - -The ObjectQL protocol needed a declarative way to express schema evolution operations - specifically updates and deletions of objects and fields. +Learn about the declarative schema migration system in ObjectQL. This implementation reference explains how to express schema evolution operations including object and field updates, deletions, and transformations through type-safe instructions. ## Solution diff --git a/docs/server.md b/docs/server.md new file mode 100644 index 00000000..56f7b211 --- /dev/null +++ b/docs/server.md @@ -0,0 +1,29 @@ +# Server Integration + +This page has been reorganized. Please visit: + +- **[Server Integration Guide](/guide/server-integration)** - Learn how to integrate ObjectQL with web servers and frameworks +- **[API Reference](/api/)** - Complete API documentation +- **[Authentication](/api/authentication)** - Securing your APIs +- **[Custom Routes](/api/custom-routes)** - Adding custom endpoints + +## Quick Links + +### For Server Setup +See the [Server Integration Guide](/guide/server-integration) for: +- Express integration +- Next.js setup +- HTTP API exposure +- REST, JSON-RPC, and GraphQL endpoints +- Middleware configuration + +### For API Configuration +- [Authentication & Authorization](/api/authentication) - Secure your APIs +- [Error Handling](/api/error-handling) - Response formats and error codes +- [Rate Limiting](/api/rate-limiting) - Protect against abuse +- [Custom API Routes](/api/custom-routes) - Extend with custom handlers + +### For Deployment +- [Configuration Guide](/guide/configuration) - Application configuration +- [Database Drivers](/guide/drivers/) - Connecting to databases +- [CLI Tools](/guide/cli) - Command-line interface diff --git a/docs/spec/action.md b/docs/spec/action.md index 74c395b9..465526c0 100644 --- a/docs/spec/action.md +++ b/docs/spec/action.md @@ -1,6 +1,6 @@ -# Action Definitions (Server Functions) +# Action (Server Function) Specification -Actions are custom Server-Side Functions attached to an object. They allow you to encapsulate complex business logic that goes beyond standard CRUD operations. +Learn how to define custom server-side functions (RPCs) attached to objects. This specification covers action metadata, parameters, permissions, and patterns for implementing complex business operations beyond standard CRUD. Unlike Hooks (which trigger automatically), Actions are explicitly invoked by the client (API, Button, Scheduled Task). diff --git a/docs/spec/app.md b/docs/spec/app.md index 2a228859..070c6ed8 100644 --- a/docs/spec/app.md +++ b/docs/spec/app.md @@ -1,6 +1,6 @@ -# Application Definition +# Application Definition Specification -Applications define high-level containers for organizing related functionality, objects, and features. They provide logical grouping, navigation structure, and branding for distinct areas of your system. +Learn how to define high-level application containers. This specification covers app metadata, branding, navigation structure, and how applications group related functionality, objects, and features into logical units. **File Naming Convention:** `.app.yml` diff --git a/docs/spec/data.md b/docs/spec/data.md index c5223642..970f573b 100644 --- a/docs/spec/data.md +++ b/docs/spec/data.md @@ -1,6 +1,6 @@ -# Data Seeding Metadata +# Data Seeding Specification -Data source files allow you to seed the database with initial data. This is useful for lookup tables, configuration, or demo content. +Learn how to define initial data and seed records. This specification covers data file formats, seeding strategies, and how to populate databases with lookup tables, configuration, and demo content. ## 1. Overview diff --git a/docs/spec/form.md b/docs/spec/form.md index 3f9c394e..0d9641f0 100644 --- a/docs/spec/form.md +++ b/docs/spec/form.md @@ -1,6 +1,6 @@ -# Form Definition +# Form Definition Specification -Forms define data entry layouts and configurations for creating and editing records. They control which fields are visible, their validation rules, and the user experience for data input. +Learn how to define data entry forms and layouts. This specification covers form metadata, field placement, validation rules, and user experience configuration for creating and editing records. **File Naming Convention:** `.form.yml` diff --git a/docs/spec/formula.md b/docs/spec/formula.md index 62dc7cdc..a21b51db 100644 --- a/docs/spec/formula.md +++ b/docs/spec/formula.md @@ -1,6 +1,6 @@ # Formula Engine Specification -Formula fields are **read-only calculated fields** that automatically derive their values from other fields, related records, or system variables. They are computed at query time and are never stored in the database. +Learn how to define calculated fields using ObjectQL's formula engine. This specification covers formula syntax, expressions, functions, and computed fields that are evaluated at query time without database storage. The Formula Engine is a core component of ObjectQL that enables declarative, metadata-driven calculations without requiring custom code for simple business logic. diff --git a/docs/spec/hook.md b/docs/spec/hook.md index 1d0588c2..2363f0cf 100644 --- a/docs/spec/hook.md +++ b/docs/spec/hook.md @@ -1,6 +1,6 @@ -# Hooks (Triggers) +# Hook (Trigger) Specification -Hooks allow you to execute server-side logic before or after database operations. They are the primary mechanism for implementing business logic, validation, and side effects in ObjectQL. +Learn how to define database hooks that execute server-side logic before or after data operations. This specification covers hook types, lifecycle events, parameters, and patterns for implementing business logic and side effects. ## 1. Overview diff --git a/docs/spec/index.md b/docs/spec/index.md index 63a3105f..d5926327 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -1,10 +1,10 @@ # Metadata Specifications -This section contains the complete metadata specifications for the ObjectQL platform. ObjectQL is a metadata-driven standard for enterprise applications - every aspect of your application is defined through structured metadata. +Complete metadata specifications for the ObjectQL platform. ObjectQL is a metadata-driven standard where every aspect of your application—data models, business logic, UI, security—is defined through structured, version-controlled metadata. 📖 **[Read the Complete Metadata Standard Guide](./metadata-standard.md)** - A comprehensive overview of the entire metadata system and how all pieces fit together. -📊 **[Implementation Progress Report](../../PROGRESS.md)** - Current implementation status of all specifications (v1.8.4 - 70% complete) +📊 **[Implementation Progress Report](../project-status.md)** - Current implementation status of all specifications ## Core Data Layer diff --git a/docs/spec/menu.md b/docs/spec/menu.md index b8556c72..0fba53ae 100644 --- a/docs/spec/menu.md +++ b/docs/spec/menu.md @@ -1,6 +1,6 @@ -# Menu Definition +# Menu Definition Specification -Menus define the navigation structure and organization of your application. They control how users access pages, objects, and features through a hierarchical menu system. +Learn how to define navigation menus and application structure. This specification covers menu metadata, hierarchical organization, menu items, and how users navigate through your application's features. **File Naming Convention:** `.menu.yml` diff --git a/docs/spec/metadata-standard.md b/docs/spec/metadata-standard.md index 950fa906..5f7c5563 100644 --- a/docs/spec/metadata-standard.md +++ b/docs/spec/metadata-standard.md @@ -1,8 +1,6 @@ -# ObjectQL Metadata Standard - Complete Guide +# ObjectQL Metadata Standard - Complete Reference -## Introduction - -ObjectQL is a **universal metadata standard** for defining enterprise applications. Instead of writing code, you define your application structure, business logic, and user interface through **structured metadata** in YAML/JSON format. +Learn the complete ObjectQL metadata standard for defining enterprise applications. This comprehensive guide covers all metadata types, from data models to business logic, UI definitions, and security—all through structured YAML/JSON configuration. **ObjectOS** interprets this metadata at runtime to generate fully functional enterprise applications - similar to how Salesforce runs on metadata, but open-source and database-agnostic. diff --git a/docs/spec/object.md b/docs/spec/object.md index c5d60af1..5dfff8c4 100644 --- a/docs/spec/object.md +++ b/docs/spec/object.md @@ -1,6 +1,6 @@ -# Object Definition +# Object Definition Specification -Object files define business entities or database tables in YAML (or JSON). They are the foundation of your application's data model and are designed to be both human-readable and AI-friendly for automated code generation. +Learn how to define business entities and database tables using ObjectQL's object metadata format. This specification covers the complete schema for `*.object.yml` files, including fields, relationships, validation, and AI-friendly metadata. **File Naming Convention:** `.object.yml` diff --git a/docs/spec/page.md b/docs/spec/page.md index 7eb25c2e..10b15411 100644 --- a/docs/spec/page.md +++ b/docs/spec/page.md @@ -1,6 +1,6 @@ -# Page Definition +# Page Definition Specification -Pages define the user interface views and layouts for your application. They control how data is displayed and how users interact with your objects. +Learn how to define user interface pages and layouts. This specification covers page metadata, component configuration, layout patterns, and how pages integrate with objects and data. **File Naming Convention:** `.page.yml` diff --git a/docs/spec/permission.md b/docs/spec/permission.md index 07dd875f..18576c70 100644 --- a/docs/spec/permission.md +++ b/docs/spec/permission.md @@ -1,6 +1,6 @@ -# Permission & Security Metadata +# Permission and Security Specification -Permission metadata defines access control rules for objects, fields, actions, and views using Role-Based Access Control (RBAC) and field-level security. +Learn how to define access control and security rules. This specification covers RBAC (Role-Based Access Control), field-level security, record-level rules, and comprehensive permission metadata for securing your application. ## 1. Overview diff --git a/docs/spec/query-language.md b/docs/spec/query-language.md index d664c441..e35cf6d1 100644 --- a/docs/spec/query-language.md +++ b/docs/spec/query-language.md @@ -1,7 +1,6 @@ +# Query Language Specification (JSON-DSL) -# ObjectQL Query Protocol (JSON-DSL) - -**Version:** 1.0.0 +Complete specification for ObjectQL's unified query protocol. This JSON-based Abstract Syntax Tree (AST) is the internal representation for all data operations, providing database-agnostic, AI-friendly, and injection-safe query capabilities. ## 1. Overview diff --git a/docs/spec/report.md b/docs/spec/report.md index adb7c698..d7f127b3 100644 --- a/docs/spec/report.md +++ b/docs/spec/report.md @@ -1,6 +1,6 @@ -# Report Definition +# Report Definition Specification -Reports define analytics, visualizations, and data exports for business intelligence and decision-making. They provide aggregated views, charts, and formatted output of your data. +Learn how to define analytics, visualizations, and data exports. This specification covers report metadata, aggregation patterns, chart types, and business intelligence features for data analysis and decision-making. **File Naming Convention:** `.report.yml` diff --git a/docs/spec/validation.md b/docs/spec/validation.md index ac66e220..f55849a9 100644 --- a/docs/spec/validation.md +++ b/docs/spec/validation.md @@ -1,6 +1,6 @@ -# Validation Rule Metadata +# Validation Rules Specification -Validation rules enforce data quality and business rules at the metadata level. They ensure data integrity before it reaches the database. Rules are designed to be both machine-executable and AI-understandable, with clear business intent. +Learn how to define validation rules that enforce data quality and business logic at the metadata level. This specification covers rule syntax, operators, conditions, and patterns for building robust data validation. ## 1. Overview diff --git a/docs/spec/view.md b/docs/spec/view.md index f2420d50..f1638223 100644 --- a/docs/spec/view.md +++ b/docs/spec/view.md @@ -1,6 +1,6 @@ -# View Definition +# View Definition Specification -Views define saved queries, filters, and display configurations for data collections. They allow users to create and share custom perspectives on object data without modifying the underlying page definitions. +Learn how to define saved queries, filters, and display configurations for data collections. This specification covers view metadata, filter syntax, column selection, and how users can create custom perspectives on object data. **File Naming Convention:** `.view.yml` diff --git a/docs/spec/workflow.md b/docs/spec/workflow.md index 07a34817..2786ee60 100644 --- a/docs/spec/workflow.md +++ b/docs/spec/workflow.md @@ -1,6 +1,6 @@ -# Workflow & Process Metadata +# Workflow and Process Specification -Workflow metadata defines automated business processes, approvals, and state-based orchestration. Workflows coordinate actions across objects, users, and external systems. They are designed to be both executable and AI-understandable with clear business intent. +Learn how to define automated business processes and workflows. This specification covers workflow states, transitions, approvals, orchestration, and patterns for implementing complex business automation. **Status: Specification complete, implementation in progress.** ## 1. Overview diff --git a/docs/tutorials/ai-agent.md b/docs/tutorials/ai-agent.md index 6d404043..7c2776f3 100644 --- a/docs/tutorials/ai-agent.md +++ b/docs/tutorials/ai-agent.md @@ -1,7 +1,6 @@ -# Building an Autonomous Data Agent +# Tutorial: Building an Autonomous AI Agent -> **Prerequisites**: [Task Manager Tutorial](./task-manager.md). -> **Concepts**: ObjectQL as a "Tool" for LLMs. +**Advanced Tutorial** - Learn how to build an autonomous AI agent using ObjectQL as the structured data layer. This tutorial covers ObjectQL as an LLM tool, implementing agent memory, and creating data-driven AI applications. In this tutorial, we will build an AI Agent that can answer questions about your data by autonomously querying the ObjectQL database. We will use OpenAI's "Function Calling" capability. diff --git a/docs/tutorials/crm-system.md b/docs/tutorials/crm-system.md index 5626b215..dfba46ab 100644 --- a/docs/tutorials/crm-system.md +++ b/docs/tutorials/crm-system.md @@ -1,8 +1,6 @@ -# Building a Micro-CRMSystem +# Tutorial: Building a CRM System -> **Prerequisites**: Completed [Build Your First App](./task-manager.md). - -In this tutorial, we will explore **Relationships**, **Validation**, and **Hooks** by building a minimal CRM (Customer Relationship Management) system. +**Intermediate Tutorial (30 minutes)** - Build a micro-CRM to master relationships, permissions, and business logic. Learn to define Account and Contact objects with 1:N relationships, add validation rules, and write beforeCreate hooks. ## 1. Define the Objects diff --git a/docs/tutorials/federation.md b/docs/tutorials/federation.md index b64281ed..eee4a229 100644 --- a/docs/tutorials/federation.md +++ b/docs/tutorials/federation.md @@ -1,7 +1,6 @@ -# Federated Data Graph +# Tutorial: Federated Data Architecture -> **Prerequisites**: [Building a Micro-CRM](./crm-system.md). -> **Requirements**: A running MongoDB instance (or use a cloud provider URI). +**Advanced Tutorial (45 minutes)** - Build a federated data graph connecting multiple databases. Learn to setup MongoDB for logs, PostgreSQL for transactional data, and query across them transparently with ObjectQL's federation capabilities. In this advanced tutorial, we will demonstrate **Data Federation**. We will connect to two different databases simultaneously: 1. **SQLite**: For structured business data (`account`, `contact`). diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index f52454c4..dbf7f67b 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -1,6 +1,6 @@ -# ObjectQL Tutorials +# ObjectQL Learning Tutorials -Welcome to the ObjectQL learning path. These tutorials are designed to take you from a complete beginner to an advanced architect. +Welcome to the ObjectQL learning path. These hands-on tutorials take you from complete beginner to advanced architect through progressive, practical examples building real applications. ## 👶 Beginner diff --git a/docs/tutorials/task-manager.md b/docs/tutorials/task-manager.md index 53939d63..efd17860 100644 --- a/docs/tutorials/task-manager.md +++ b/docs/tutorials/task-manager.md @@ -1,8 +1,6 @@ -# Build Your First App: Task Manager +# Tutorial: Build Your First Task Manager -> **Prerequisites**: Node.js v18+, NPM/PNPM. - -In this tutorial, we will build a simple Task Management backend without writing any SQL or API boilerplate. +**Beginner Tutorial (15 minutes)** - Create your first ObjectQL application with a simple task management system. Learn to define schemas, run the development server, and manage data through the Studio interface. ## 1. Setup