From ef699f8e28f852285f85a7afb131511afe47535a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 16 Jan 2026 07:44:42 +0000
Subject: [PATCH 1/6] Initial plan


From 638df647e0e4c99747e6f16270b8698a155b6b12 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 16 Jan 2026 07:49:10 +0000
Subject: [PATCH 2/6] Add comprehensive architecture documentation in Chinese
 and English

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
---
 content/docs/architecture.en.mdx    | 260 ++++++++++++++++++++++++++++
 content/docs/architecture.zh-CN.mdx | 260 ++++++++++++++++++++++++++++
 content/docs/meta.en.json           |   2 +-
 content/docs/meta.zh-CN.json        |   2 +-
 4 files changed, 522 insertions(+), 2 deletions(-)
 create mode 100644 content/docs/architecture.en.mdx
 create mode 100644 content/docs/architecture.zh-CN.mdx

diff --git a/content/docs/architecture.en.mdx b/content/docs/architecture.en.mdx
new file mode 100644
index 0000000..95a0dcf
--- /dev/null
+++ b/content/docs/architecture.en.mdx
@@ -0,0 +1,260 @@
+---
+title: Architecture
+description: ObjectStack Enterprise Architecture - Cross-Database Edition
+---
+
+# ObjectStack Enterprise Architecture
+
+## Core Value Proposition
+
+**Write Once, Run on Any DB**
+
+ObjectStack is a database-agnostic full-stack application development framework. Through standardized protocols (ObjectQL/UI), it enables developers to build portable and scalable enterprise applications without being constrained by underlying database technology stacks.
+
+---
+
+## Layer 1: Protocol Layer (ObjectStack Protocols)
+
+### Positioning
+The "isolation layer" between business logic and underlying technology.
+
+### Core Value
+Application developers only need to understand ObjectQL syntax, without needing to know whether the underlying database is MySQL, PostgreSQL, or Oracle. Even if the underlying database changes, the upper-level business code (Schema and UI) doesn't need to change a single line.
+
+### Main Protocols
+- **ObjectQL**: Unified data query and manipulation language
+- **ObjectUI**: Unified UI rendering protocol
+- **Schema Definition**: Data model definition in JSON Schema format
+
+---
+
+## Layer 2: Core Engines (The Engines)
+
+Independent and decoupled core engine layer providing cross-database capabilities.
+
+### 1. ObjectQL (Backend Core: Multi-Database Adapter Engine)
+
+This is the true **"Universal Connector"**. It's no longer bound to SQLite but comes with a complete driver adapter layer.
+
+#### Core Modules
+
+##### AST Compiler (Abstract Syntax Tree Compiler)
+Compiles ObjectQL's JSON queries into an abstract syntax tree.
+
+##### Dialect Transpiler
+The key to cross-database support:
+- **MySQL**: Transpiles to `LIMIT x OFFSET y`
+- **Oracle**: Transpiles to `ROWNUM` or `OFFSET FETCH`
+- **PostgreSQL**: Optimizes queries using JSONB features
+- **SQL Server**: Transpiles to `TOP` or `OFFSET FETCH NEXT`
+
+##### Connection Pool
+Manages database connection pools, supporting high concurrency.
+
+##### Migration Engine
+Automatically generates ALTER TABLE DDL statements for different databases based on JSON Schema changes to synchronize table structures.
+
+#### Supported Drivers
+
+- `@objectql/driver-mysql` - MySQL database driver
+- `@objectql/driver-postgres` - PostgreSQL database driver
+- `@objectql/driver-oracle` - Oracle database driver
+- `@objectql/driver-sqlserver` - SQL Server database driver
+- `@objectql/driver-sqlite` - SQLite driver (for development environment or edge computing only)
+
+### 2. ObjectUI (Frontend Core: Rendering Engine)
+
+#### Positioning
+Completely decoupled from the backend. It only recognizes ObjectQL's API data format and doesn't care which database the data comes from.
+
+#### Core Features
+- **Database Agnostic**: Interacts entirely through ObjectQL API
+- **Component-based Design**: Reusable UI component library
+- **Responsive Rendering**: Adapts to different devices and screen sizes
+- **Theme Customization**: Supports custom styles and themes
+
+---
+
+## Layer 3: ObjectOS (Server-side Runtime / Middleware)
+
+### Positioning
+A server-oriented Headless CMS or BaaS (Backend as a Service) platform.
+
+It's no longer just a local app kernel, but a web service that can be deployed in Docker/Kubernetes.
+
+### Core Responsibilities
+
+#### 1. Unified Authentication Center (Auth Middleware)
+
+- **ObjectQL Integration**: Provides `allowRead`, `allowWrite` and other permission mechanisms
+- **Enterprise Authentication Integration**: Supports LDAP / OAuth2 / OIDC / SAML
+- **Token Parsing**: Injects user roles into ObjectQL context
+- **Fine-grained Access Control**: Row-level and field-level permission management
+
+#### 2. Plugin & Extension Container (Server-side Plugins)
+
+##### IO Extensions
+Not just local IO, but integration with various enterprise services:
+- **Redis**: Caching layer
+- **S3/OSS**: Object storage
+- **RabbitMQ/Kafka**: Message queues
+
+##### Webhooks
+Send HTTP callbacks to external systems when data changes.
+
+##### Custom Business Logic
+Supports developers in writing custom plugins to extend business logic.
+
+#### 3. Multi-Environment Management
+
+ObjectOS allows the same codebase to switch between different environments:
+
+- **Development Environment**: Uses `driver-sqlite` (local file, no database installation required)
+- **Testing Environment**: Uses `driver-mysql` (CI/CD automatic deployment)
+- **Production Environment**: Uses `driver-oracle` (integrates with legacy core systems)
+
+Switch environments through configuration files without modifying code.
+
+---
+
+## Layer 4: Applications & Delivery (The Applications)
+
+Under this architecture, the form of applications has evolved. No longer just ".oos files," but **"microservices" or "business modules"**.
+
+### DevOps-Friendly Delivery
+
+1. **Development Phase**: Developers write Schema and Plugin code
+2. **Packaging Phase**: Package into Docker Image through ObjectOS
+3. **Deployment Phase**: Deploy to enterprise private cloud or public cloud
+
+### SaaS Platform
+
+Quickly build multi-tenant SaaS platforms based on ObjectOS.
+
+#### Tenant Isolation Strategies
+
+##### Strategy A: Schema Discriminator
+All tenants share one database, distinguished by fields.
+
+**Advantages**:
+- High resource utilization
+- Low management cost
+
+**Use Cases**:
+- Large number of tenants
+- Moderate data volume
+
+##### Strategy B: Database per Tenant
+Each tenant uses an independent database instance.
+
+**Advantages**:
+- Complete data isolation
+- Independent performance optimization
+- Easy backup and recovery
+
+**Use Cases**:
+- Small number of tenants
+- High data isolation requirements
+
+**ObjectQL Advantage**: Upper-level business code doesn't need to change at all; tenant isolation can be achieved by simply configuring ObjectQL's connection strategy.
+
+---
+
+## Target Customers
+
+### 1. IT Departments of Medium to Large Enterprises (Platform Strategy)
+
+#### Pain Points
+- Dozens of legacy systems within the enterprise
+- Multiple databases like SQL Server, Oracle
+- Severe data silos, difficult system integration
+
+#### Solution
+Use ObjectOS as a **"Data Platform"**:
+- Connect various heterogeneous databases at the bottom
+- Provide unified ObjectQL API upward
+- Frontend, whether React or Vue, only calls ObjectQL
+- No need to worry about underlying database complexity
+
+### 2. SaaS Startups
+
+#### Pain Points
+- Want to quickly build SaaS products
+- Don't want to spend time writing CRUD, permissions, multi-tenancy logic
+- Need to focus on core business value
+
+#### Solution
+Use ObjectStack as the foundation:
+- Set up database table structure (Schema) in one day
+- Quickly generate admin backend (ObjectUI)
+- Focus on writing core business plugins
+
+### 3. Low-Code Platform Vendors
+
+#### Pain Points
+- Many low-code platforms are tied to their own proprietary databases
+- Customers worry about vendor lock-in
+- High migration costs
+
+#### Solution
+ObjectQL supports cross-database:
+- Customers can use Oracle if they want
+- Can migrate to cloud when needed
+- No vendor lock-in whatsoever
+
+---
+
+## Technical Advantages Summary
+
+### 1. Database Agnostic
+- Write once, run on any database
+- Reduce migration costs and risks
+
+### 2. Standardized Protocols
+- ObjectQL provides unified data access interface
+- ObjectUI provides unified frontend rendering protocol
+
+### 3. Enterprise-Grade Features
+- Multi-tenancy support
+- Unified authentication center
+- High availability and scalability
+
+### 4. Development Efficiency
+- Out-of-the-box components and features
+- Reduce repetitive code writing
+- Fast iteration from prototype to production
+
+### 5. Flexible Deployment
+- Supports on-premises, private cloud, public cloud
+- Docker/Kubernetes friendly
+- Multi-environment configuration management
+
+---
+
+## Architecture Evolution Roadmap
+
+### Current Stage
+- Core engine development
+- Mainstream database driver support
+- Basic component library construction
+
+### Near-term Goals
+- Enterprise authentication integration
+- More database drivers
+- Performance optimization and monitoring
+
+### Long-term Vision
+- Complete ecosystem
+- Community plugin marketplace
+- AI-assisted development tools
+
+---
+
+## Getting Started
+
+To get started with ObjectStack, check out our [Getting Started](/docs/getting-started) guide.
+
+Learn more about each component:
+- [ObjectQL Documentation](/docs/objectql)
+- [ObjectUI Documentation](/docs/objectui)
+- [ObjectOS Documentation](/docs/objectos)
diff --git a/content/docs/architecture.zh-CN.mdx b/content/docs/architecture.zh-CN.mdx
new file mode 100644
index 0000000..9001cc5
--- /dev/null
+++ b/content/docs/architecture.zh-CN.mdx
@@ -0,0 +1,260 @@
+---
+title: 项目架构
+description: ObjectStack 企业级架构图谱 - 跨数据库版本
+---
+
+# ObjectStack 企业级架构图谱
+
+## 核心价值
+
+**Write Once, Run on Any DB（一次开发，任意数据库运行）**
+
+ObjectStack 是一个数据库无关 (Database-Agnostic) 的全栈应用开发框架。它通过标准化的协议 (ObjectQL/UI)，让开发者能够构建可移植、可扩展的企业级应用，而无需被底层的数据库技术栈所束缚。
+
+---
+
+## 第一层：协议层 (ObjectStack Protocols)
+
+### 定位
+业务逻辑与底层技术的"隔离带"。
+
+### 核心价值
+应用开发者只需要懂 ObjectQL 语法，完全不需要知道底层是 MySQL、PostgreSQL 还是 Oracle。即使底层数据库换了，上层业务代码（Schema 和 UI）一行都不用改。
+
+### 主要协议
+- **ObjectQL**：统一的数据查询和操作语言
+- **ObjectUI**：统一的 UI 渲染协议
+- **Schema Definition**：JSON Schema 格式的数据模型定义
+
+---
+
+## 第二层：核心引擎 (The Engines)
+
+独立且解耦的核心引擎层，提供跨数据库的能力。
+
+### 1. ObjectQL (后端核心：多数据库适配引擎)
+
+这是真正的**"万能连接器"**。它不再绑定 SQLite，而是自带一套驱动适配层 (Driver Adapters)。
+
+#### 核心模块
+
+##### AST Compiler（抽象语法树编译器）
+把 ObjectQL 的 JSON 查询编译成抽象语法树。
+
+##### Dialect Transpiler（方言转译器）
+这是跨数据库的关键：
+- **MySQL**：转译为 `LIMIT x OFFSET y`
+- **Oracle**：转译为 `ROWNUM` 或 `OFFSET FETCH`
+- **PostgreSQL**：利用其 JSONB 特性优化查询
+- **SQL Server**：转译为 `TOP` 或 `OFFSET FETCH NEXT`
+
+##### Connection Pool（连接池管理）
+管理数据库连接池，支持高并发。
+
+##### Migration Engine（迁移引擎）
+根据 JSON Schema 的变更，自动生成不同数据库的 ALTER TABLE DDL 语句，同步表结构。
+
+#### 支持的驱动 (Drivers)
+
+- `@objectql/driver-mysql` - MySQL 数据库驱动
+- `@objectql/driver-postgres` - PostgreSQL 数据库驱动
+- `@objectql/driver-oracle` - Oracle 数据库驱动
+- `@objectql/driver-sqlserver` - SQL Server 数据库驱动
+- `@objectql/driver-sqlite` - SQLite 驱动（仅用于开发环境或边缘计算）
+
+### 2. ObjectUI (前端核心：渲染引擎)
+
+#### 定位
+与后端彻底解耦。它只认 ObjectQL 的 API 数据格式，不关心数据是从哪种数据库里取出来的。
+
+#### 核心特性
+- **数据库无关**：完全通过 ObjectQL API 交互
+- **组件化设计**：可复用的 UI 组件库
+- **响应式渲染**：自适应不同设备和屏幕尺寸
+- **主题定制**：支持自定义样式和主题
+
+---
+
+## 第三层：ObjectOS (服务端运行时 / 中间件)
+
+### 定位
+面向服务端的 Headless CMS 或 BaaS (Backend as a Service) 平台。
+
+它不再只是一个本地 App 的内核，而是一个可以部署在 Docker / Kubernetes 里的 Web 服务。
+
+### 核心职责
+
+#### 1. 统一鉴权中心 (Auth Middleware)
+
+- **ObjectQL 集成**：提供 `allowRead`、`allowWrite` 等权限机制
+- **企业认证对接**：支持 LDAP / OAuth2 / OIDC / SAML
+- **Token 解析**：将用户角色注入到 ObjectQL 的上下文中
+- **细粒度权限控制**：行级、字段级权限管理
+
+#### 2. 插件与扩展容器 (Server-side Plugins)
+
+##### IO 扩展
+不仅是本地 IO，而是对接各种企业级服务：
+- **Redis**：缓存层
+- **S3/OSS**：对象存储
+- **RabbitMQ/Kafka**：消息队列
+
+##### Webhooks
+数据变更时，向外部系统发送 HTTP 回调。
+
+##### 自定义业务逻辑
+支持开发者编写自定义插件，扩展业务逻辑。
+
+#### 3. 多环境管理
+
+ObjectOS 允许一套代码在不同环境切换：
+
+- **开发环境**：使用 `driver-sqlite`（本地文件，无需安装数据库）
+- **测试环境**：使用 `driver-mysql`（CI/CD 自动部署）
+- **生产环境**：使用 `driver-oracle`（对接旧核心系统）
+
+通过配置文件即可切换，无需修改代码。
+
+---
+
+## 第四层：应用与交付 (The Applications)
+
+在这种架构下，应用的形态也变了。不再只是".oos 文件"，而是**"微服务"或"业务模块"**。
+
+### DevOps 友好型交付
+
+1. **开发阶段**：开发者编写 Schema 和 Plugin 代码
+2. **打包阶段**：通过 ObjectOS 打包成 Docker Image
+3. **部署阶段**：部署到企业私有云或公有云
+
+### SaaS 平台化
+
+基于 ObjectOS 可以快速搭建多租户的 SaaS 平台。
+
+#### 租户隔离方案
+
+##### 方案 A：Schema Discriminator（架构区分器）
+所有租户共用一个数据库，通过字段区分租户。
+
+**优点**：
+- 资源利用率高
+- 管理成本低
+
+**适用场景**：
+- 租户数量多
+- 数据量适中
+
+##### 方案 B：Database per Tenant（每租户独立数据库）
+每个租户使用独立的数据库实例。
+
+**优点**：
+- 数据完全隔离
+- 性能可独立优化
+- 易于备份和恢复
+
+**适用场景**：
+- 租户数量少
+- 对数据隔离要求高
+
+**ObjectQL 的优势**：上层业务代码完全不用改，只需要配置 ObjectQL 的连接策略即可实现租户隔离。
+
+---
+
+## 目标客户
+
+### 1. 中大型企业的 IT 部门（中台战略）
+
+#### 痛点
+- 企业内部有几十个老旧系统
+- 有 SQL Server、Oracle 等多种数据库
+- 数据孤岛严重，系统集成困难
+
+#### 解决方案
+用 ObjectOS 作为**"数据中台"**：
+- 连接底层各种异构数据库
+- 向上提供统一的 ObjectQL API
+- 前端不管是 React 还是 Vue，都只调 ObjectQL
+- 不用管底层数据库有多复杂
+
+### 2. SaaS 创业公司
+
+#### 痛点
+- 想快速做 SaaS 产品
+- 不想花时间写 CRUD、权限、多租户逻辑
+- 需要专注于核心业务价值
+
+#### 解决方案
+直接用 ObjectStack 作为底座：
+- 一天之内搭好数据库表结构（Schema）
+- 快速生成管理后台（ObjectUI）
+- 专注于编写核心业务插件
+
+### 3. 低代码平台厂商
+
+#### 痛点
+- 很多低代码平台绑定了自己的私有数据库
+- 客户担心厂商锁定 (Vendor Lock-in)
+- 迁移成本高
+
+#### 解决方案
+ObjectQL 支持跨数据库：
+- 客户想用 Oracle 就用 Oracle
+- 想迁移到云就迁移到云
+- 完全没有 Vendor Lock-in
+
+---
+
+## 技术优势总结
+
+### 1. 数据库无关性
+- 一次开发，任意数据库运行
+- 降低迁移成本和风险
+
+### 2. 标准化协议
+- ObjectQL 提供统一的数据访问接口
+- ObjectUI 提供统一的前端渲染协议
+
+### 3. 企业级特性
+- 多租户支持
+- 统一鉴权中心
+- 高可用和可扩展性
+
+### 4. 开发效率
+- 开箱即用的组件和功能
+- 减少重复性代码编写
+- 快速原型到生产的迭代
+
+### 5. 灵活部署
+- 支持本地、私有云、公有云
+- Docker/Kubernetes 友好
+- 多环境配置管理
+
+---
+
+## 架构演进路线图
+
+### 当前阶段
+- 核心引擎开发
+- 主流数据库驱动支持
+- 基础组件库建设
+
+### 近期目标
+- 企业级认证集成
+- 更多数据库驱动
+- 性能优化和监控
+
+### 长期愿景
+- 完整的生态系统
+- 社区插件市场
+- AI 辅助开发工具
+
+---
+
+## 开始使用
+
+要开始使用 ObjectStack，请查看我们的[快速开始](/docs/getting-started)指南。
+
+了解各个组件的详细信息：
+- [ObjectQL 文档](/docs/objectql)
+- [ObjectUI 文档](/docs/objectui)
+- [ObjectOS 文档](/docs/objectos)
diff --git a/content/docs/meta.en.json b/content/docs/meta.en.json
index fe5f742..8ff445c 100644
--- a/content/docs/meta.en.json
+++ b/content/docs/meta.en.json
@@ -1,4 +1,4 @@
 {
   "title": "Documentation",
-  "pages": ["index", "getting-started", "objectui", "objectql", "objectos", "i18n-guide"]
+  "pages": ["index", "getting-started", "architecture", "objectui", "objectql", "objectos", "i18n-guide"]
 }
diff --git a/content/docs/meta.zh-CN.json b/content/docs/meta.zh-CN.json
index 6fe2a24..4ccca52 100644
--- a/content/docs/meta.zh-CN.json
+++ b/content/docs/meta.zh-CN.json
@@ -1,4 +1,4 @@
 {
   "title": "文档",
-  "pages": ["index", "getting-started", "objectui", "objectql", "objectos", "i18n-guide"]
+  "pages": ["index", "getting-started", "architecture", "objectui", "objectql", "objectos", "i18n-guide"]
 }

From 75a01b4709a3aa8e0f99ca6bd460f568b4a58754 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 16 Jan 2026 07:57:28 +0000
Subject: [PATCH 3/6] Initial plan


From 3d8749ba8dfab79672133a466b08b6171a00901e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 16 Jan 2026 07:59:40 +0000
Subject: [PATCH 4/6] Fix link check workflow by updating action version to
 1.0.17

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
---
 .github/workflows/link-check.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml
index e7084ee..f31d923 100644
--- a/.github/workflows/link-check.yml
+++ b/.github/workflows/link-check.yml
@@ -23,7 +23,7 @@ jobs:
         uses: actions/checkout@v4
       
       - name: Check links in content directory
-        uses: gaurav-nelson/github-action-markdown-link-check@v1.0.15
+        uses: gaurav-nelson/github-action-markdown-link-check@1.0.17
         with:
           use-quiet-mode: 'yes'
           use-verbose-mode: 'no'
@@ -32,7 +32,7 @@ jobs:
           check-modified-files-only: ${{ github.event_name == 'pull_request' && 'yes' || 'no' }}
       
       - name: Check links in root markdown files
-        uses: gaurav-nelson/github-action-markdown-link-check@v1.0.15
+        uses: gaurav-nelson/github-action-markdown-link-check@1.0.17
         with:
           use-quiet-mode: 'yes'
           use-verbose-mode: 'no'

From ecbdfc86bdc14a1b87bcbc78e1ef3be9e96537fe Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 16 Jan 2026 08:07:00 +0000
Subject: [PATCH 5/6] Initial plan


From e2ff62a565bbaf3671fe950117b4d59a1c0848d7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 16 Jan 2026 08:09:27 +0000
Subject: [PATCH 6/6] Fix link check workflow base branch from master to main

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
---
 .github/workflows/link-check.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml
index f31d923..d73fd16 100644
--- a/.github/workflows/link-check.yml
+++ b/.github/workflows/link-check.yml
@@ -30,6 +30,7 @@ jobs:
           config-file: '.github/markdown-link-check-config.json'
           folder-path: 'content/'
           check-modified-files-only: ${{ github.event_name == 'pull_request' && 'yes' || 'no' }}
+          base-branch: 'main'
       
       - name: Check links in root markdown files
         uses: gaurav-nelson/github-action-markdown-link-check@1.0.17
@@ -39,3 +40,4 @@ jobs:
           config-file: '.github/markdown-link-check-config.json'
           file-path: './README.md'
           check-modified-files-only: ${{ github.event_name == 'pull_request' && 'yes' || 'no' }}
+          base-branch: 'main'