Merge pull request #330 from objectstack-ai/copilot/update-related-documentation-again

Author: hotlong

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
 
 ```

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

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

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

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 |