Add enterprise architecture documentation for cross-database ObjectStack #16

Copilot · 2026-01-16T07:44:43Z

Added comprehensive architecture documentation describing ObjectStack's database-agnostic design: a 4-layer system enabling "Write Once, Run on Any DB" through standardized protocols.

Changes

New Documentation Files

content/docs/architecture.zh-CN.mdx - Chinese version (260 lines)
content/docs/architecture.en.mdx - English version (260 lines)
Updated navigation metadata in both meta.zh-CN.json and meta.en.json

Architecture Layers Documented

Layer 1: Protocol Layer

ObjectQL, ObjectUI, and Schema Definition as isolation between business logic and database technology

Layer 2: Core Engines

ObjectQL: Multi-database adapter with AST compiler, dialect transpiler for MySQL/PostgreSQL/Oracle/SQL Server/SQLite, connection pooling, and schema migration engine
ObjectUI: Database-agnostic frontend renderer

Layer 3: ObjectOS Runtime

Authentication middleware (LDAP/OAuth2/OIDC/SAML)
Plugin system for Redis, S3/OSS, message queues
Environment-based driver selection (SQLite for dev, production databases for deploy)

Layer 4: Applications

Multi-tenancy strategies: shared schema vs. database-per-tenant
Docker/Kubernetes deployment patterns

Targets three customer segments: enterprise IT (data platform consolidation), SaaS startups (rapid development), and low-code vendors (vendor lock-in elimination).

Original prompt

This section details on the original issue you should resolve

<issue_title>编写项目总体架构文档</issue_title>
<issue_description>按照这个核心设定，我们重新梳理架构。现在的重点是：屏蔽底层数据库差异，提供统一的协议接口。
ObjectStack 企业级架构图谱 (Cross-Database Edition)
这个架构的核心价值在于：Write Once, Run on Any DB（一次开发，任意数据库运行）。
第一层：协议层 (ObjectStack Protocols)
定位：业务逻辑与底层技术的“隔离带”。

价值：应用开发者只需要懂 ObjectQL 语法，完全不需要知道底层是 MySQL、PostgreSQL 还是 Oracle。即使底层数据库换了，上层业务代码（Schema 和 UI）一行都不用改。
第二层：核心引擎 (The Engines) - 独立且解耦

ObjectQL (后端核心：多数据库适配引擎)
这是真正的**“万能连接器”。它不再绑定 SQLite，而是自带一套驱动适配层 (Driver Adapters)**。

核心模块：

AST Compiler：把 ObjectQL 的 JSON 查询编译成抽象语法树。

Dialect Transpiler (方言转译器)：这是跨数据库的关键。

如果是 MySQL，转译为 LIMIT x OFFSET y。

如果是 Oracle，转译为 ROWNUM 或 OFFSET FETCH。

如果是 PostgreSQL，利用其 JSONB 特性优化查询。

Connection Pool：管理数据库连接池，支持高并发。

Migration Engine：根据 JSON Schema 的变更，自动生成不同数据库的 ALTER TABLE DDL 语句，同步表结构。

支持的驱动 (Drivers)：

@objectql/driver-mysql

@objectql/driver-postgres

@objectql/driver-oracle

@objectql/driver-sqlserver

@objectql/driver-sqlite (仅用于开发环境或边缘计算)

ObjectUI (前端核心：渲染引擎)

定位：与后端彻底解耦。它只认 ObjectQL 的 API 数据格式，不关心数据是从哪种数据库里取出来的。
第三层：ObjectOS (服务端运行时 / 中间件)
定位：面向服务端的 Headless CMS 或 BaaS (Backend as a Service) 平台。
它不再只是一个本地 App 的内核，而是一个可以部署在 Docker / Kubernetes 里的 Web 服务。
它的核心职责变成了“企业级胶水”：

统一鉴权中心 (Auth Middleware)

ObjectQL 依然只提供 allowRead 机制。

ObjectOS 负责对接企业现有的 LDAP / OAuth2 / OIDC / SAML。

ObjectOS 解析 Token，将用户角色注入到 ObjectQL 的上下文中。

插件与扩展容器 (Server-side Plugins)

IO 扩展：不仅是本地 IO，而是对接 Redis (缓存)、S3/OSS (对象存储)、RabbitMQ/Kafka (消息队列)。

Webhooks：数据变更时，向外部系统发送 HTTP 回调。

多环境管理

ObjectOS 允许一套代码在不同环境切换：

开发环境：使用 driver-sqlite (本地文件，无需装库)。

测试环境：使用 driver-mysql (CI/CD 自动部署)。

生产环境：使用 driver-oracle (对接旧核心系统)。
第四层：应用与交付 (The Applications)
在这种架构下，应用的形态也变了。不再只是“.oos 文件”，而是**“微服务”或“业务模块”**。

DevOps 友好型交付

开发者写好 Schema 和 Plugin 代码。

通过 ObjectOS 打包成 Docker Image。

部署到企业私有云。

SaaS 平台化

你可以基于 ObjectOS 搭建一个多租户的 SaaS 平台。

租户隔离：

方案 A：所有租户共用一个 Postgres 库，字段区分 (Schema Discriminator)。

方案 B：每个租户一个独立的 MySQL 数据库 (Database per Tenant)。

ObjectQL 的优势：上层业务代码完全不用改，只需要配置 ObjectQL 的连接策略即可实现租户隔离。
重新总结：这套东西卖给谁？
现在的定位不再是“卖给个人做记账软件”，而是：

卖给中大型企业的 IT 部门 (中台战略)

痛点：企业内部有几十个老旧系统，有 SQL Server 的，有 Oracle 的，数据孤岛严重。

解法：用 ObjectOS 作为**“数据中台”**。它连接底层各种异构数据库，向上提供统一的 ObjectQL API。前端不管是 React 还是 Vue，都只调 ObjectQL，不用管底层多乱。

卖给 SaaS 创业公司

痛点：创业公司想做 SaaS，但不想花时间写 CRUD、权限、多租户逻辑。

解法：直接用 ObjectStack 作为底座。一天之内把数据库表结构（Schema）和管理后台（ObjectUI）搭好，专注于写核心业务插件。

卖给低代码平台厂商

痛点：很多低代码平台绑定了自己的私有数据库，客户不放心。

解法：ObjectQL 支持跨数据库。客户想存 Oracle 就存 Oracle，想迁云就迁云，完全没有 Vendor Lock-in (厂商锁定)。
一句话定义新架构
ObjectStack 是一个数据库无关 (Database-Agnostic) 的全栈应用开发框架。它通过标准化的协议 (ObjectQL/UI)，让开发者能够构建可移植、可扩展的企业级应用，而无需被底层的数据库技术栈所束缚。</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes 编写项目总体架构文档 #15

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

vercel · 2026-01-16T07:44:47Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
docs	Ready	Preview, Comment	Jan 16, 2026 8:27am

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

github-actions · 2026-01-16T07:52:23Z

🚀 Preview Deployment

This pull request will be automatically deployed to Vercel.

Preview Links

📝 Documentation: Will be available once Vercel deployment completes
🌍 Languages: English (/en/docs) and Chinese (/zh-CN/docs)

Build Status

Check the CI workflow for build status and any errors.

Automated preview information for PR #16

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

…s-documentation

github-actions · 2026-01-16T08:06:12Z

🚀 Preview Deployment

This pull request will be automatically deployed to Vercel.

Preview Links

📝 Documentation: Will be available once Vercel deployment completes
🌍 Languages: English (/en/docs) and Chinese (/zh-CN/docs)

Build Status

Check the CI workflow for build status and any errors.

Automated preview information for PR #16

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

…on-references

github-actions · 2026-01-16T08:27:00Z

🚀 Preview Deployment

This pull request will be automatically deployed to Vercel.

Preview Links

📝 Documentation: Will be available once Vercel deployment completes
🌍 Languages: English (/en/docs) and Chinese (/zh-CN/docs)

Build Status

Check the CI workflow for build status and any errors.

Automated preview information for PR #16

Copilot

Pull request overview

This PR adds comprehensive enterprise architecture documentation for ObjectStack, describing its database-agnostic design philosophy and 4-layer architecture that enables "Write Once, Run on Any DB" functionality through standardized protocols.

Changes:

Added bilingual architecture documentation (English and Chinese) describing ObjectStack's cross-database capabilities, layer architecture, target customers, and technical advantages
Updated navigation metadata to include the new architecture documentation page
Upgraded GitHub Actions link-check workflow to version 1.0.17 with improved PR-based checking

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
content/docs/architecture.en.mdx	English architecture documentation covering 4-layer system (Protocol, Core Engines, ObjectOS Runtime, Applications) with detailed technical specifications
content/docs/architecture.zh-CN.mdx	Chinese version of architecture documentation with identical structure and content
content/docs/meta.en.json	Added "architecture" to English navigation pages array
content/docs/meta.zh-CN.json	Added "architecture" to Chinese navigation pages array
.github/workflows/link-check.yml	Updated GitHub Actions markdown link checker from v1.0.15 to 1.0.17 and added base-branch parameter

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-16T08:32:06Z

content/docs/architecture.en.mdx

+- **Oracle**: Transpiles to `ROWNUM` or `OFFSET FETCH`
+- **PostgreSQL**: Optimizes queries using JSONB features
+- **SQL Server**: Transpiles to `TOP` or `OFFSET FETCH NEXT`


There are extra backticks at the end of these lines. The closing backtick should be removed from both lines to properly format the inline code.

Initial plan

ef699f8

Copilot AI assigned Copilot and hotlong Jan 16, 2026

Copilot started work on behalf of hotlong January 16, 2026 07:45 View session

vercel bot deployed to Preview January 16, 2026 07:45 View deployment

Add comprehensive architecture documentation in Chinese and English

638df64

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

vercel bot deployed to Preview January 16, 2026 07:49 View deployment

Copilot AI changed the title ~~[WIP] Write overall project architecture documentation~~ Add enterprise architecture documentation for cross-database ObjectStack Jan 16, 2026

Copilot AI requested a review from hotlong January 16, 2026 07:51

Copilot finished work on behalf of hotlong January 16, 2026 07:51

hotlong approved these changes Jan 16, 2026

View reviewed changes

github-actions bot added documentation Improvements or additions to documentation i18n labels Jan 16, 2026

Copilot AI and others added 3 commits January 16, 2026 07:57

Initial plan

75a01b4

Fix link check workflow by updating action version to 1.0.17

3d8749b

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Merge pull request #17 from objectstack-ai/copilot/update-action-step…

db54840

…s-documentation

github-actions bot added the workflows label Jan 16, 2026

vercel bot deployed to Preview January 16, 2026 08:06 View deployment

Copilot AI and others added 3 commits January 16, 2026 08:07

Initial plan

ecbdfc8

Fix link check workflow base branch from master to main

e2ff62a

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Merge pull request #18 from objectstack-ai/copilot/update-documentati…

62f309a

…on-references

vercel bot deployed to Preview January 16, 2026 08:27 View deployment

hotlong marked this pull request as ready for review January 16, 2026 08:29

Copilot AI review requested due to automatic review settings January 16, 2026 08:29

hotlong merged commit 942a6e3 into main Jan 16, 2026
8 checks passed

Copilot started reviewing on behalf of hotlong January 16, 2026 08:29 View session

Copilot AI reviewed Jan 16, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add enterprise architecture documentation for cross-database ObjectStack #16

Add enterprise architecture documentation for cross-database ObjectStack #16

Uh oh!

Copilot AI commented Jan 16, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 16, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 16, 2026

Uh oh!

github-actions bot commented Jan 16, 2026

Uh oh!

github-actions bot commented Jan 16, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add enterprise architecture documentation for cross-database ObjectStack #16

Add enterprise architecture documentation for cross-database ObjectStack #16

Uh oh!

Conversation

Copilot AI commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Architecture Layers Documented

Comments on the Issue (you are @copilot in this section)

Uh oh!

vercel bot commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 16, 2026

🚀 Preview Deployment

Preview Links

Build Status

Uh oh!

github-actions bot commented Jan 16, 2026

🚀 Preview Deployment

Preview Links

Build Status

Uh oh!

github-actions bot commented Jan 16, 2026

🚀 Preview Deployment

Preview Links

Build Status

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Jan 16, 2026 •

edited

Loading

vercel bot commented Jan 16, 2026 •

edited

Loading