Skip to content

Commit 9aa67b0

Browse files
xuyushun441-sysxuyushun441-sys
authored
Merge pull request #154 from objectstack-ai/copilot/refactor-kernel-and-server
2 parents 39d254a + a9ae8d3 commit 9aa67b0

34 files changed

+2518
-173
lines changed

‎ARCHITECTURE.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -56,19 +56,23 @@ All ObjectOS plugins must conform to this lifecycle for consistency and predicta
5656

5757
### ObjectOS Repository (Runtime Implementation)
5858
- **Location**: This repository
59-
- **Purpose**: Implements the runtime engine that executes ObjectQL metadata
59+
- **Purpose**: Implements the runtime engine and plugin ecosystem
6060
- **Key Packages**:
61-
- `@objectos/kernel` - Core execution engine
62-
- `@objectos/server` - HTTP API layer
61+
- `@objectstack/runtime` - Microkernel with plugin lifecycle management
62+
- `@objectos/plugin-server` - NestJS HTTP server plugin
63+
- `@objectos/plugin-better-auth` - Authentication plugin
64+
- `@objectos/plugin-audit-log` - Audit logging plugin
65+
- `@objectos/kernel` - **DEPRECATED** (use @objectstack/runtime)
66+
- `@objectos/server` - **DEPRECATED** (use @objectos/plugin-server)
6367

6468
## Core Architectural Principle
6569

66-
> **"Kernel handles logic, Drivers handle data, Server handles HTTP."**
70+
> **"Runtime manages plugins, Plugins implement features, Drivers handle data."**
6771
6872
This separation ensures:
6973
1. **Testability**: Each layer can be tested independently
70-
2. **Flexibility**: Swap databases without changing business logic
71-
3. **Scalability**: Scale HTTP layer independently from data layer
74+
2. **Flexibility**: Add/remove features via plugins without touching core
75+
3. **Scalability**: Plugins can be distributed and loaded dynamically
7276
4. **Maintainability**: Clear boundaries reduce coupling
7377

7478
## Layer 1: Metadata Protocol (ObjectQL)

‎MICROKERNEL_MIGRATION_SUMMARY.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
# ObjectOS Microkernel Migration Summary
2+
3+
## Overview
4+
5+
This document summarizes the architectural refactoring completed to transition ObjectOS from a monolithic kernel architecture to a microkernel plugin-based architecture.
6+
7+
**Date**: February 1, 2026
8+
**Version**: 0.3.0-alpha
9+
**Status**: In Progress
10+
11+
## What Changed
12+
13+
### Deprecated Packages
14+
15+
1. **@objectos/kernel** (v0.2.0)
16+
- **Status**: Deprecated but functional
17+
- **Replacement**: `@objectstack/runtime`
18+
- **Migration Path**: See [migration guide](./docs/guide/migration-from-kernel.md)
19+
20+
2. **@objectos/server** (v0.2.0)
21+
- **Status**: Deprecated but functional
22+
- **Replacement**: `@objectos/plugin-server`
23+
- **Migration Path**: See [migration guide](./docs/guide/migration-from-kernel.md)
24+
25+
### New Packages
26+
27+
1. **@objectstack/runtime** (v0.1.0)
28+
- Microkernel with plugin lifecycle management
29+
- Service registry and event bus
30+
- Dependency resolution with topological sorting
31+
- Built-in logger
32+
33+
2. **@objectos/plugin-server** (v0.1.0)
34+
- NestJS HTTP server as a runtime plugin
35+
- REST, GraphQL, and WebSocket support
36+
- Authentication middleware integration
37+
- CORS configuration
38+
39+
## Architecture Changes
40+
41+
### Before (Monolithic)
42+
43+
```
44+
┌────────────────────────┐
45+
│ @objectos/server │ ← Standalone NestJS server
46+
├────────────────────────┤
47+
│ @objectos/kernel │ ← Monolithic kernel
48+
│ • Permissions │
49+
│ • Plugins │
50+
│ • Metrics │
51+
│ • Workflows │
52+
│ • Hot Reload │
53+
├────────────────────────┤
54+
│ @objectql/core │
55+
└────────────────────────┘
56+
```
57+
58+
### After (Microkernel + Plugins)
59+
60+
```
61+
┌────────────────────────────────────────┐
62+
│ Plugin Ecosystem │
63+
│ │
64+
│ @objectos/plugin-server │ ← HTTP Server
65+
│ @objectos/plugin-better-auth │ ← Auth
66+
│ @objectos/plugin-audit-log │ ← Audit
67+
│ @objectos/plugin-permissions (TODO) │ ← Permissions
68+
│ @objectos/plugin-workflow (TODO) │ ← Workflows
69+
│ @objectos/plugin-metrics (TODO) │ ← Metrics
70+
│ │
71+
├────────────────────────────────────────┤
72+
│ @objectstack/runtime │ ← Microkernel
73+
│ • Plugin Lifecycle │
74+
│ • Service Registry │
75+
│ • Event Bus │
76+
│ • Dependency Resolution │
77+
├────────────────────────────────────────┤
78+
│ @objectql/core │
79+
└────────────────────────────────────────┘
80+
```
81+
82+
## Implementation Details
83+
84+
### Files Created
85+
86+
1. **Documentation**
87+
- `/docs/guide/migration-from-kernel.md` - Complete migration guide
88+
- `/docs/guide/plugin-development.md` - Plugin development guide
89+
- `/packages/kernel/README.md` - Deprecation notice
90+
- `/packages/server/README.md` - Deprecation notice
91+
- `/packages/plugins/server/README.md` - Server plugin documentation
92+
93+
2. **Server Plugin**
94+
- `/packages/plugins/server/package.json` - Package definition
95+
- `/packages/plugins/server/src/plugin.ts` - Plugin implementation
96+
- `/packages/plugins/server/src/bootstrap.ts` - Bootstrap entry point
97+
- `/packages/plugins/server/src/index.ts` - Public API
98+
- `/packages/plugins/server/src/*` - Copied NestJS modules
99+
100+
3. **Runtime Enhancements**
101+
- Updated `/packages/runtime/src/index.ts` - Better exports
102+
103+
### Files Modified
104+
105+
1. **Project Configuration**
106+
- `/pnpm-workspace.yaml` - Exclude deprecated packages, include runtime
107+
- `/package.json` - Update scripts, remove runtime patch
108+
- `/README.md` - Update architecture table
109+
- `/ARCHITECTURE.md` - Update architectural principles
110+
111+
2. **Deprecation Markers**
112+
- `/packages/kernel/package.json` - Add deprecation notice
113+
- `/packages/server/package.json` - Add deprecation notice
114+
115+
## Key Benefits
116+
117+
### 1. Modularity
118+
- Features are now isolated in separate plugins
119+
- Plugins can be enabled/disabled independently
120+
- Third-party plugins are easier to develop
121+
122+
### 2. Testability
123+
- Test plugins in isolation
124+
- Mock plugins for unit testing
125+
- Clear plugin boundaries
126+
127+
### 3. Maintainability
128+
- Reduced core complexity
129+
- Clear separation of concerns
130+
- Easier to understand and debug
131+
132+
### 4. Extensibility
133+
- Plugin ecosystem for community contributions
134+
- Standard plugin interface
135+
- Dependency management
136+
137+
### 5. Spec Compliance
138+
- Follows @objectstack/spec protocol
139+
- Consistent with ecosystem standards
140+
- Future-proof architecture
141+
142+
## Migration Timeline
143+
144+
### Phase 1: Foundation (Current)
145+
- ✅ Create microkernel architecture
146+
- ✅ Deprecate monolithic packages
147+
- ✅ Create server plugin
148+
- ✅ Write documentation
149+
- ⏳ Fix TypeScript compilation issues
150+
151+
### Phase 2: Feature Migration (Next)
152+
- ⏳ Create permission system plugin
153+
- ⏳ Create workflow engine plugin
154+
- ⏳ Create metrics plugin
155+
- ⏳ Migrate hot reload to runtime core
156+
157+
### Phase 3: Testing & Validation
158+
- ⏳ Unit tests for runtime
159+
- ⏳ Integration tests for plugins
160+
- ⏳ Migration testing
161+
- ⏳ Performance benchmarks
162+
163+
### Phase 4: Community Migration (Future)
164+
- ⏳ Plugin registry
165+
- ⏳ Community plugin templates
166+
- ⏳ Plugin certification
167+
- ⏳ Migration tooling
168+
169+
## Known Issues
170+
171+
### TypeScript Compilation
172+
Some TypeScript errors remain in the server plugin:
173+
- Missing type definitions for `pg` and `better-sqlite3`
174+
- PluginContext compatibility issues
175+
- Express request type extensions
176+
177+
**Status**: To be fixed in next iteration
178+
179+
### Testing
180+
- Server plugin has not been tested yet
181+
- Integration tests need to be written
182+
- Migration path needs validation
183+
184+
**Status**: Pending
185+
186+
## Next Steps
187+
188+
1. **Fix Compilation Errors** (Priority: HIGH)
189+
- Add missing @types/* packages
190+
- Fix PluginContext compatibility
191+
- Resolve Express typing issues
192+
193+
2. **Create Feature Plugins** (Priority: MEDIUM)
194+
- Extract permission system from kernel
195+
- Extract workflow engine from kernel
196+
- Extract metrics from kernel
197+
198+
3. **Testing** (Priority: HIGH)
199+
- Write unit tests for runtime
200+
- Write integration tests for plugins
201+
- Test migration path
202+
203+
4. **Documentation** (Priority: MEDIUM)
204+
- Add more examples
205+
- Create video tutorials
206+
- Update API documentation
207+
208+
## Migration Support
209+
210+
### For Users
211+
- **Migration Guide**: See `/docs/guide/migration-from-kernel.md`
212+
- **Plugin Guide**: See `/docs/guide/plugin-development.md`
213+
- **Examples**: See `/packages/plugins/*/README.md`
214+
215+
### For Contributors
216+
- **Architecture**: See `/ARCHITECTURE.md`
217+
- **Contributing**: See `/CONTRIBUTING.md`
218+
- **Roadmap**: See `/ROADMAP.md`
219+
220+
## Conclusion
221+
222+
The migration to a microkernel architecture represents a significant improvement in ObjectOS's design. While there are still some compilation issues to resolve, the foundation is solid and the benefits are clear.
223+
224+
The plugin-based architecture provides better modularity, testability, and extensibility, making ObjectOS more suitable for enterprise use and community contributions.
225+
226+
## References
227+
228+
- [@objectstack/spec](https://github.com/objectstack-ai/spec)
229+
- [Plugin Development Guide](./docs/guide/plugin-development.md)
230+
- [Migration Guide](./docs/guide/migration-from-kernel.md)
231+
- [Runtime Documentation](./packages/runtime/README.md)

‎README.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -86,11 +86,12 @@ This ensures interoperability across the ObjectStack ecosystem (ObjectQL, Object
8686
| Package | Role | Description |
8787
| :--- | :--- | :--- |
8888
| **`@objectstack/runtime`** | **The Kernel** | Micro-kernel with plugin lifecycle and service registry. |
89-
| **`@objectos/kernel`** | **The Brain** | The core logic engine. Wraps ObjectQL, manages plugins, and handles the event bus. |
90-
| **`@objectos/server`** | **The Gateway** | NestJS application layer. Handles HTTP/WS traffic, Middlewares, and Guards. |
91-
| **`@objectos/plugin-auth`** | **Auth** | Authentication strategies (Local, OAuth2, Enterprise SSO). |
92-
| **`@objectos/plugin-workflow`** | **Logic** | Workflow engine and trigger runner. |
89+
| **`@objectos/plugin-server`** | **The Gateway** | NestJS HTTP server as a runtime plugin. |
90+
| **`@objectos/plugin-better-auth`** | **Auth** | Authentication strategies (Local, OAuth2, Enterprise SSO). |
91+
| **`@objectos/plugin-audit-log`** | **Audit** | Comprehensive audit logging and field history tracking. |
9392
| **`@objectos/presets`** | **Config** | Standard system objects (`_users`, `_roles`, `_audit_log`). |
93+
| **`@objectos/kernel`** | **DEPRECATED** | ⚠️ Use `@objectstack/runtime` instead |
94+
| **`@objectos/server`** | **DEPRECATED** | ⚠️ Use `@objectos/plugin-server` instead |
9495

9596
---
9697

0 commit comments

Comments
 (0)