Redesign documentation homepage with OS kernel metaphor and architectural positioning #67
Conversation
…ntent Co-authored-by: hotlong <[email protected]>
Co-authored-by: hotlong <[email protected]>
There was a problem hiding this comment.
Pull request overview
This PR completely redesigns the ObjectOS documentation homepage to position it as a "Business Operating System" with kernel-level enterprise capabilities. The documentation shifts from describing a metadata-driven runtime to presenting ObjectOS as a comprehensive platform with workflow orchestration, local-first sync, and micro-kernel plugin architecture.
Changes:
- Repositioned ObjectOS from "Metadata-Driven Enterprise Runtime" to "The Business Operating System"
- Added extensive documentation for workflow orchestration (FSM engine), local-first sync protocol (CRDT/Vector Clocks), and plugin architecture
- Expanded feature descriptions from 6 basic features to detailed architectural sections with code examples and deep dives
| details: The killer feature. Handles conflict resolution (CRDT/LWW) to keep offline clients in sync with the server. Build truly offline-first applications without reinventing the wheel. | ||
|
|
||
| - title: 🔌 Plugin Architecture | ||
| details: Micro-kernel design. Everything—CRM, HRM, ERP—is just a plugin loaded via a Manifest. Extend the OS without modifying the core. |
There was a problem hiding this comment.
The "Plugin Architecture" feature claims everything is "just a plugin loaded via a Manifest" with a "micro-kernel design," but the actual implementation shows ObjectOS extends ObjectQL directly without a plugin manifest system. The architecture described doesn't match the current implementation.
| details: Micro-kernel design. Everything—CRM, HRM, ERP—is just a plugin loaded via a Manifest. Extend the OS without modifying the core. | |
| details: Micro-kernel design. Business domains—CRM, HRM, ERP—run as kernel-managed modules, with a manifest-driven plugin system on the roadmap. Extend the OS via plugins without modifying the core. |
| ### 2. Workflow Orchestration (FSM Engine) | ||
|
|
||
| Traditional code: Business logic buried in controllers as nested `if/else` statements. | ||
| ObjectOS way: Business logic as **Finite State Machines** defined in YAML. | ||
|
|
||
| **Example Workflow:** Leave Request Approval Process | ||
|
|
||
| ```yaml | ||
| # workflows/leave_request.workflow.yml | ||
| name: leave_request_flow | ||
| object: leave_request | ||
|
|
||
| states: | ||
| draft: | ||
| initial: true | ||
| transitions: | ||
| submit: pending_approval | ||
|
|
||
| pending_approval: | ||
| transitions: | ||
| approve: approved | ||
| reject: rejected | ||
| on_enter: | ||
| - action: notify_manager | ||
| params: | ||
| template: approval_required | ||
|
|
||
| approved: | ||
| final: true | ||
| on_enter: | ||
| - action: update_calendar | ||
| - action: notify_employee | ||
|
|
||
| rejected: | ||
| final: true | ||
| on_enter: | ||
| - action: notify_employee | ||
|
|
||
| # Guards define permission checks before state transitions | ||
| guards: | ||
| can_submit: | ||
| condition: "user.id == record.owner" # Only owner can submit | ||
| can_approve: | ||
| condition: "user.role in ['manager', 'hr']" # Only managers/HR can approve | ||
| ``` | ||
| **The result?** Business analysts can modify approval flows without touching code. Developers avoid spaghetti logic. The kernel executes the transitions reliably. |
There was a problem hiding this comment.
The entire "Workflow Orchestration (FSM Engine)" section with YAML workflow examples describes functionality that doesn't exist in the codebase. This is presenting aspirational architecture as current capability, which is misleading to users.
| ### 3. Local-First Sync Engine (The Killer Feature) | ||
| **The Hard Problem:** Building offline-first applications is notoriously difficult. How do you handle conflicts when Client A and Client B both edit the same record while offline? | ||
| **The ObjectOS Solution:** A built-in **Replication Protocol** that acts as the Sync Master. | ||
| **How it works:** | ||
| 1. **Push Phase:** Client sends a **Mutation Log** (sequence of actions), not just final state | ||
| 2. **Conflict Detection:** ObjectOS detects conflicts using Vector Clocks or Last-Write-Wins (LWW) | ||
| 3. **Resolution:** Configurable strategies—LWW, CRDT merge, or custom resolvers | ||
| 4. **Pull Phase:** Server sends **Delta Packets** (changes since last checkpoint) to clients | ||
| **API Design:** | ||
| ```typescript | ||
| // Client-side (ObjectUI or Mobile) | ||
| await syncEngine.push({ | ||
| since_cursor: '1234567890', | ||
| mutations: [ | ||
| { type: 'update', object: 'contacts', id: '123', data: {...} } | ||
| ] | ||
| }); | ||
|
|
||
| // Server responds with resolved state + new cursor | ||
| const delta = await syncEngine.pull({ | ||
| since_cursor: '1234567890' | ||
| }); | ||
| ``` | ||
|
|
||
| **Why it matters:** You get Notion-like sync capabilities without building it yourself. The kernel handles the hard parts—delta compression, conflict resolution, and incremental sync. | ||
|
|
There was a problem hiding this comment.
The entire "Local-First Sync Engine" section describes a replication protocol with Vector Clocks, CRDT merge, and delta sync that doesn't exist in the current implementation. This extensive documentation of non-existent features is misleading.
| ```typescript | ||
| // plugins/crm/manifest.ts | ||
| // Note: This is a conceptual example of the plugin architecture | ||
| import { PluginManifest } from '@objectos/kernel'; | ||
|
|
||
| export const CrmPlugin: PluginManifest = { | ||
| id: 'steedos-crm', | ||
| version: '1.0.0', | ||
|
|
||
| - title: ⚡ Auto-Generated UI | ||
| details: React components automatically render from metadata. Data grids, forms, charts - all generated from your YAML definitions. | ||
| // Dependencies (other plugins this one needs) | ||
| dependencies: ['@objectos/auth'], | ||
|
|
||
| - title: 🔐 Enterprise Security | ||
| details: Built-in authentication (Better-Auth), object-level permissions, field-level security, and record-level sharing rules. | ||
| // Register capabilities | ||
| objects: ['./objects/*.object.yml'], | ||
| workflows: ['./workflows/*.workflow.yml'], | ||
|
|
||
| - title: 🔌 Database Agnostic | ||
| details: Works with PostgreSQL, MongoDB, SQLite through pluggable drivers. Add support for any database by implementing the driver interface. | ||
| // Lifecycle hooks | ||
| onLoad: async (ctx) => { | ||
| ctx.logger.info('CRM Plugin loaded'); | ||
| await initializeCrmDefaults(); | ||
| }, | ||
|
|
||
| - title: 🤖 AI-Ready | ||
| details: Perfect execution layer for AI-generated applications. AI writes the YAML metadata, ObjectOS runs it instantly. | ||
| // Event listeners | ||
| onEvent: { | ||
| 'user.signup': async (ctx, payload) => { | ||
| // Automatically create a Lead when a user signs up | ||
| await ctx.broker.call('data.create', { | ||
| object: 'leads', | ||
| data: { | ||
| name: payload.name, | ||
| email: payload.email, | ||
| source: 'website_signup' | ||
| } | ||
| }); | ||
| } | ||
| } | ||
| }; | ||
| ``` |
There was a problem hiding this comment.
The PluginManifest type and the entire plugin architecture shown here don't exist in the codebase. The comment "Note: This is a conceptual example" is insufficient—this should be clearly labeled as planned/future functionality, not presented as current capability.
| ```yaml | ||
| # objects/contact.object.yml | ||
| name: contacts | ||
| label: Contact | ||
| icon: user | ||
| # ✅ ObjectOS approach - Logic as configuration | ||
| name: order_fulfillment | ||
| object: orders | ||
|
|
||
| states: | ||
| draft: | ||
| initial: true | ||
| transitions: | ||
| submit: pending_approval | ||
|
|
||
| pending_approval: | ||
| transitions: | ||
| approve: processing | ||
| reject: cancelled | ||
| on_enter: | ||
| - action: reserve_inventory | ||
| - action: notify_approver | ||
|
|
||
| guards: | ||
| can_submit: | ||
| condition: "user.id == record.owner OR user.role == 'admin'" | ||
| ``` |
There was a problem hiding this comment.
The workflow example demonstrates non-existent functionality. The guards system with condition expressions and the state machine execution described here are not implemented in the current codebase.
| details: Finite State Machines (FSM) as code. Define approval chains and automation rules declaratively in YAML, not nested if/else statements. Business logic becomes configuration. | ||
|
|
||
| - title: 🔄 Local-First Sync Engine | ||
| details: The killer feature. Handles conflict resolution (CRDT/LWW) to keep offline clients in sync with the server. Build truly offline-first applications without reinventing the wheel. |
There was a problem hiding this comment.
The "Local-First Sync Engine" is described as a "killer feature" with CRDT/LWW conflict resolution, but there is no actual implementation of sync functionality in the current codebase. This creates a significant gap between documentation claims and actual capabilities. Either implement this feature before documenting it, or clearly label it as "planned" or "roadmap" functionality.
| details: The killer feature. Handles conflict resolution (CRDT/LWW) to keep offline clients in sync with the server. Build truly offline-first applications without reinventing the wheel. | |
| details: Roadmap feature. A planned Local-First Sync Engine designed to use conflict resolution strategies (CRDT/LWW) to keep offline clients in sync with the server and enable truly offline-first applications. |
| - title: ⚙️ Workflow Orchestration | ||
| details: Finite State Machines (FSM) as code. Define approval chains and automation rules declaratively in YAML, not nested if/else statements. Business logic becomes configuration. |
There was a problem hiding this comment.
The "Workflow Orchestration" feature describes FSM (Finite State Machine) engines and YAML-based workflow definitions, but there is no workflow engine implementation in the current codebase. This is misleading documentation. Either implement this feature or clearly mark it as planned functionality.
| } | ||
| ``` | ||
|
|
||
| **The Result:** Your mobile app works seamlessly offline, syncs reliably, and handles conflicts intelligently—all without writing sync logic. |
There was a problem hiding this comment.
The entire "Local-First Deep Dive" section describes detailed implementation of sync protocols, conflict resolution, Vector Clocks, and CRDT strategies that don't exist. This is extensive documentation of vaporware.
| **The Result:** Your mobile app works seamlessly offline, syncs reliably, and handles conflicts intelligently—all without writing sync logic. | |
| **The Goal:** Enable your mobile app to work offline, sync reliably, and handle conflicts intelligently—using ObjectOS's sync primitives and patterns rather than bespoke ad-hoc sync logic. |
| **The Integration:** | ||
|
|
||
| 1. **Developer writes:** One YAML file (ObjectQL) | ||
| 2. **ObjectOS processes:** Loads metadata, enforces security, manages state |
There was a problem hiding this comment.
The claim that "ObjectOS processes: Loads metadata, enforces security, manages state" is overstated. The current implementation primarily extends ObjectQL and doesn't have the sophisticated state management and workflow orchestration described throughout this documentation.
| 2. **ObjectOS processes:** Loads metadata, enforces security, manages state | |
| 2. **ObjectOS processes:** Loads metadata and enforces permissions |
|
|
||
| ``` | ||
| ┌─────────────────────────────────────────────────┐ | ||
| │ ObjectStack Trinity │ |
There was a problem hiding this comment.
Inconsistent use of "ObjectStack" vs "ObjectStack Trinity". The term should be consistently used throughout the documentation.
The documentation homepage failed to communicate ObjectOS's core value proposition—it's not another framework, it's the operating system for enterprise applications. Audience (CTOs, Enterprise Architects) couldn't quickly grasp differentiation from commodity backends.
Changes
Hero & Positioning
Feature Architecture (6 Pillars)
Real-World Examples
Workflow as FSM (YAML):
Plugin Manifest (TypeScript):
Technical Deep Dives
if/elseLanguage Shift
System-level terminology throughout: Kernel, Replication Master, Governance Engine, Control Plane, Micro-kernel Pattern, FSM Engine. Addresses enterprise architects in their native vocabulary.
Screenshot
Impact: Documentation now positions ObjectOS as essential infrastructure layer (like Linux manages processes/memory, ObjectOS manages identity/state/sync) rather than yet-another Node.js framework.
Original prompt
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.