From e9dc69e9ff58850b68fc616851e835efdbdae95f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 27 Jan 2026 15:38:33 +0000 Subject: [PATCH 1/2] Initial plan From 60651fac77ddd66f0ae292299b389c4a8db06f9c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 27 Jan 2026 15:44:38 +0000 Subject: [PATCH 2/2] Update documentation with new package types (objectql, gateway, adapter) Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- ARCHITECTURE.md | 80 +++++++++++++++++++ PROTOCOL_REFERENCE.md | 10 ++- README.md | 2 +- content/docs/developers/writing-plugins.mdx | 13 +++ .../references/kernel/manifest/Manifest.mdx | 2 +- 5 files changed, 104 insertions(+), 3 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 29b2ad51f..6a851abd5 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -219,6 +219,86 @@ Each plugin: --- +## 📦 Package Types & Microkernel Architecture + +ObjectStack follows a **microkernel architecture** where different package types serve distinct roles in the system lifecycle. The `type` field in the manifest (`objectstack.config.ts`) determines a package's role and initialization order. + +### Package Type Hierarchy + +``` +External Request (Browser/Mobile) + │ + ▼ +[ adapter ] ←─ HTTP Server Container (Express, Hono, Fastify, Serverless) + │ • Role: Runtime host/container + │ • Cardinality: Singleton (one per runtime) + │ • Examples: @objectstack/adapter-express, @objectstack/adapter-hono + ▼ +[ gateway ] ←─ API Protocol Layer (GraphQL, REST, RPC, OData) + │ • Role: Protocol translation + │ • Cardinality: Multiple (can coexist) + │ • Examples: @objectstack/gateway-graphql, @objectstack/gateway-rest + ▼ +[ Kernel ] ←─ Core orchestration (ObjectOS Runtime) + │ + ▼ +[ objectql] ←─ Core Data Engine + │ • Role: Query engine and business logic layer + │ • Examples: @objectstack/objectql + ▼ +[ driver ] ←─ Southbound: Database/External Service Adapters + │ • Role: Data persistence and external integrations + │ • Examples: @objectstack/driver-postgres, @objectstack/driver-mongodb + ▼ + Database +``` + +### Package Type Definitions + +| Type | Description | Cardinality | Layer | Examples | +|:-----|:------------|:------------|:------|:---------| +| **adapter** | Runtime container - HTTP server adapter | Singleton | Outermost | Express, Hono, Fastify, Lambda | +| **gateway** | API protocol entry point | Multiple | North | GraphQL, REST, RPC, OData | +| **objectql** | Core data engine implementation | Singleton | Core | Query engine, business logic | +| **driver** | Database/external service adapter | Multiple | South | Postgres, MongoDB, S3, Salesforce | +| **plugin** | General-purpose functionality extension | Multiple | App | CRM, BI, Analytics | +| **app** | Business application package | Multiple | App | Sales App, Service App | +| **module** | Reusable code library/shared module | Multiple | Lib | Utilities, helpers | + +### Lifecycle Ordering + +The kernel initializes packages in a specific order to ensure proper dependency resolution: + +1. **Adapter** preparation (HTTP server setup) +2. **ObjectQL** engine initialization (core data layer) +3. **Driver** connections (database, external services) +4. **Gateway** registration (API protocol handlers) +5. **App/Plugin** loading (business logic) + +This ordering ensures that: +- The HTTP server is ready before routes are registered +- The data engine is initialized before drivers connect +- Drivers are connected before gateways need to query data +- Gateways are ready before apps register business endpoints + +### Adapter vs Gateway Distinction + +**Key Architectural Difference:** + +- **Adapter** = The "what" and "where" (which HTTP framework, which runtime environment) + - Handles raw HTTP Request/Response objects + - Manages server lifecycle (listen, close) + - One adapter per runtime instance + - Cannot coexist (can't run Express + Hono on same port) + +- **Gateway** = The "how" (which API protocol) + - Translates protocol to internal `Call` format + - Multiple gateways can coexist + - Registers routes on the adapter + - Example: Same server can expose both GraphQL and REST APIs + +--- + ## 🔐 Security & Permission Model ``` diff --git a/PROTOCOL_REFERENCE.md b/PROTOCOL_REFERENCE.md index 44bae603a..83dcc9451 100644 --- a/PROTOCOL_REFERENCE.md +++ b/PROTOCOL_REFERENCE.md @@ -84,7 +84,7 @@ Defines the "Runtime Environment" and platform capabilities. | File | Schema | Purpose | | :--- | :--- | :--- | -| `manifest.zod.ts` | `ManifestSchema` | Application/plugin manifest (`objectstack.config.ts`) | +| `manifest.zod.ts` | `ManifestSchema` | Application/plugin manifest (`objectstack.config.ts`) with 7 package types: app, plugin, driver, module, objectql, gateway, adapter | | `datasource.zod.ts` | `DatasourceSchema` | Data source connection configurations | | `driver.zod.ts` | `DriverSchema` | Database driver definitions and options | | `driver/postgres.zod.ts` | `PostgresConfigSchema` | PostgreSQL-specific driver configuration | @@ -100,6 +100,14 @@ Defines the "Runtime Environment" and platform capabilities. | `scoped-storage.zod.ts` | `ScopedStorageSchema` | Scoped key-value storage | **Key Features:** +- Microkernel architecture with 7 distinct package types for proper separation of concerns + - **adapter**: Runtime containers (Express, Hono, Fastify, Serverless) + - **gateway**: API protocols (GraphQL, REST, RPC, OData) + - **objectql**: Core data engine implementation + - **driver**: Database/external service adapters (Postgres, MongoDB, S3) + - **plugin**: General-purpose functionality extensions + - **app**: Business application packages + - **module**: Reusable code libraries - Pluggable architecture with manifest-based configuration - Multi-driver support (PostgreSQL, MongoDB, and extensible) - Event-driven architecture with pub/sub diff --git a/README.md b/README.md index 9f95c43fc..3ff122788 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ Defines the "Shape of Interaction" for rendering interfaces. ### 3. System Protocol (ObjectOS) - 14 Protocols Defines the "Runtime Environment" and platform capabilities. -- **Manifest:** Application packaging (`objectstack.config.ts`) +- **Manifest:** Application packaging (`objectstack.config.ts`) with support for 7 package types: `app`, `plugin`, `driver`, `module`, `objectql`, `gateway`, `adapter` - **Identity:** Authentication, Roles, Territories, Licenses, Organizations - **Integration:** Webhooks, API contracts, ETL Mappings - **Datasource:** Driver definitions for PostgreSQL, MongoDB, and extensible drivers diff --git a/content/docs/developers/writing-plugins.mdx b/content/docs/developers/writing-plugins.mdx index 6fcdee61d..2afc377cd 100644 --- a/content/docs/developers/writing-plugins.mdx +++ b/content/docs/developers/writing-plugins.mdx @@ -704,6 +704,19 @@ npm run build } ``` +**Package Type Options:** + +The `type` field in the `objectstack` configuration can be one of: +- `plugin` - General-purpose functionality extension (default for most plugins) +- `app` - Business application package +- `driver` - Database/external service adapter (Postgres, MongoDB, S3) +- `module` - Reusable code library/shared module +- `objectql` - Core data engine implementation +- `gateway` - API protocol entry point (GraphQL, REST, RPC) +- `adapter` - Runtime container (Express, Hono, Fastify, Serverless) + +For most use cases, use `plugin` for business logic extensions and `driver` for data source integrations. + --- ## 🚀 Publishing diff --git a/content/docs/references/kernel/manifest/Manifest.mdx b/content/docs/references/kernel/manifest/Manifest.mdx index 65a6878fb..c3fadffd3 100644 --- a/content/docs/references/kernel/manifest/Manifest.mdx +++ b/content/docs/references/kernel/manifest/Manifest.mdx @@ -9,7 +9,7 @@ description: Manifest Schema Reference | :--- | :--- | :--- | :--- | | **id** | `string` | ✅ | Unique package identifier (reverse domain style) | | **version** | `string` | ✅ | Package version (semantic versioning) | -| **type** | `Enum<'app' \| 'plugin' \| 'driver' \| 'module'>` | ✅ | Type of package | +| **type** | `Enum<'app' \| 'plugin' \| 'driver' \| 'module' \| 'objectql' \| 'gateway' \| 'adapter'>` | ✅ | Type of package | | **name** | `string` | ✅ | Human-readable package name | | **description** | `string` | optional | Package description | | **permissions** | `string[]` | optional | Array of required permission strings |