Merge pull request #16 from objectstack-ai/copilot/create-architecture-documentation

Author: hotlong

.github/workflows/link-check.yml

@@ -23,19 +23,21 @@ 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'
           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@v1.0.15
+        uses: gaurav-nelson/github-action-markdown-link-check@1.0.17
         with:
           use-quiet-mode: 'yes'
           use-verbose-mode: 'no'
           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'

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)