┌─────────────────────────────────────────────────────────┐
│ @objectstack/core (ISSUES HERE) │
│ ┌───────────────────────────────────────────────────┐ │
│ │ ObjectKernel (219 lines) │ │
│ │ ├─ resolveDependencies() ←──┐ │ │
│ │ ├─ createContext() │ │ │
│ │ ├─ services: Map ←──────────┼─── DUPLICATE │ │
│ │ ├─ hooks: Map │ │ │
│ │ └─ bootstrap() │ │ │
│ └───────────────────────────────┼───────────────────┘ │
│ ┌───────────────────────────────┼───────────────────┐ │
│ │ EnhancedObjectKernel (496 lines) │ │
│ │ ├─ resolveDependencies() ←──┘ DUPLICATE │ │
│ │ ├─ createContext() ← DUPLICATE │ │
│ │ ├─ services: Map ←────────────── DUPLICATE │ │
│ │ ├─ hooks: Map ← DUPLICATE │ │
│ │ ├─ bootstrap() ← DUPLICATE │ │
│ │ └─ pluginLoader ← Has services too │ │
│ └───────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Logger (306 lines) ← WRONG LOCATION │ │
│ │ ├─ Pino implementation │ │
│ │ └─ Should be standalone package │ │
│ └───────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ contracts/ ← WRONG LOCATION │ │
│ │ ├─ IDataEngine ← Should be in spec │ │
│ │ ├─ IHttpServer ← Should be in spec │ │
│ │ └─ ILogger ← Should be in spec │ │
│ └───────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ PluginLoader (435 lines) ← TOO MANY JOBS │ │
│ │ ├─ Validation │ │
│ │ ├─ Lifecycle Management │ │
│ │ ├─ Loading │ │
│ │ └─ Dependency Analysis │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
❌ Code Duplication: ~40%
❌ Responsibilities: 4 (Kernel + Logger + Contracts + Loading)
❌ Service Storage: 3 locations
❌ Missing Abstractions: 4 interfaces
┌─────────────────────────────────────────────────────────┐
│ @objectstack/spec (Protocol Foundation) │
│ ┌───────────────────────────────────────────────────┐ │
│ │ contracts/ ← MOVED HERE │ │
│ │ ├─ IDataEngine │ │
│ │ ├─ IHttpServer │ │
│ │ ├─ ILogger │ │
│ │ ├─ IServiceRegistry ← NEW │ │
│ │ ├─ IPluginValidator ← NEW │ │
│ │ ├─ IStartupOrchestrator ← NEW │ │
│ │ └─ IPluginLifecycleEvents ← NEW │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
↑
│ implements
│
┌──────────────────────────┴──────────────────────────────┐
│ @objectstack/logger (NEW PACKAGE) │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Logger (306 lines) ← EXTRACTED │ │
│ │ ├─ adapters/ │ │
│ │ │ ├─ pino.ts │ │
│ │ │ ├─ console.ts │ │
│ │ │ └─ winston.ts (future) │ │
│ │ └─ Implements ILogger │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
↑
│ uses
│
┌──────────────────────────┴──────────────────────────────┐
│ @objectstack/core (REFACTORED) │
│ ┌───────────────────────────────────────────────────┐ │
│ │ ObjectKernelBase (150 lines) ← NEW BASE CLASS │ │
│ │ ├─ resolveDependencies() ← SINGLE IMPL │ │
│ │ ├─ createContext() ← SINGLE IMPL │ │
│ │ ├─ services: IServiceRegistry ← INTERFACE │ │
│ │ └─ hooks: TypedEventBus<Events> ← TYPED │ │
│ └───────────────────────────────────────────────────┘ │
│ ↑ ↑ │
│ │ │ │
│ ┌───────┴──────┐ ┌───────┴──────┐ │
│ ┌────▼──────────────┐ │ ┌────▼──────────────┐ │ │
│ │ ObjectKernel │ │ │ EnhancedKernel │ │ │
│ │ (100 lines) │ │ │ (200 lines) │ │ │
│ │ ✅ Lightweight │ │ │ ✅ Composition │ │ │
│ └───────────────────┘ │ └───┬───────────────┘ │ │
│ │ │
│ Uses │ │
│ ┌──────────────────────────▼───────────────────────┐ │
│ │ Component Services (SEPARATED) │ │
│ │ ├─ PluginValidator (60 lines) │ │
│ │ ├─ ServiceLifecycleManager (80 lines) │ │
│ │ ├─ StartupOrchestrator (100 lines) │ │
│ │ ├─ DependencyAnalyzer (50 lines) │ │
│ │ └─ PluginLoader (150 lines, simplified) │ │
│ └───────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Service Registries (ABSTRACTED) │ │
│ │ ├─ BasicServiceRegistry (80 lines) │ │
│ │ └─ AdvancedServiceRegistry (150 lines) │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
✅ Code Duplication: <5% (eliminated)
✅ Responsibilities: 1 (Kernel lifecycle only)
✅ Service Storage: 1 location (IServiceRegistry)
✅ Abstractions: 7 interfaces defined
✅ Code Reduction: -400 lines
| Metric | Before (v0.6.1) | After (v1.0.0) | Change |
|---|---|---|---|
| Total Core Lines | 2,828 | ~2,400 | -428 lines ✅ |
| Code Duplication | ~40% | <5% | -35% ✅ |
| Test Coverage | ~70% | >90% | +20% ✅ |
| Cyclomatic Complexity (max) | 15+ | <10 | Simpler ✅ |
| Number of Responsibilities (Core) | 4 | 1 | -3 ✅ |
| Metric | Before | After | Improvement |
|---|---|---|---|
| Package Cohesion | 6/10 | 9/10 | +50% ✅ |
| Separation of Concerns | 6/10 | 9/10 | +50% ✅ |
| Interface Abstraction | 4/10 | 9/10 | +125% ✅ |
| Dependency Clarity | 8/10 | 10/10 | +25% ✅ |
| Overall Architecture Score | 7/10 | 9/10 | +29% ✅ |
| Metric | Before | After | Improvement |
|---|---|---|---|
| Bug Fix Time | Baseline | -50% | Faster ✅ |
| Test Writing Time | Baseline | -30% | Easier ✅ |
| New Feature Time | Baseline | -40% | Clearer ✅ |
| Onboarding Time | Baseline | -40% | Simpler ✅ |
┌───────────────────────────────────────────────────────────┐
│ PHASE 1: Foundation (Week 1-2) │
├───────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │Extract │───▶│Move Contracts│───▶│Create │ │
│ │Interfaces │ │to Spec │ │Logger Pkg │ │
│ └─────────────┘ └──────────────┘ └─────────────┘ │
└───────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────┐
│ PHASE 2: Kernel Refactoring (Week 3-4) │
├───────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │Create │───▶│Refactor │───▶│Refactor │ │
│ │KernelBase │ │ObjectKernel │ │Enhanced │ │
│ └─────────────┘ └──────────────┘ └─────────────┘ │
│ │ │
│ └─────────────┐ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ Eliminate 120 lines │ │
│ │ of duplicate code │ │
│ └────────────────────────┘ │
└───────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────┐
│ PHASE 3: Split Responsibilities (Week 5) │
├───────────────────────────────────────────────────────────┤
│ PluginLoader (435 lines) │
│ │ │
│ ├──▶ PluginValidator (60 lines) │
│ ├──▶ ServiceLifecycleManager (80 lines) │
│ ├──▶ StartupOrchestrator (100 lines) │
│ ├──▶ DependencyAnalyzer (50 lines) │
│ └──▶ PluginLoader (150 lines, simplified) │
└───────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────┐
│ PHASE 4-6: Service Registry, Events, Testing (Week 6-8) │
├───────────────────────────────────────────────────────────┤
│ Week 6: Service Registry Abstraction │
│ Week 7: Typed Event System │
│ Week 8: Testing & Documentation │
└───────────────────────────────────────────────────────────┘
│
▼
┌──────────────┐
│ v1.0.0 │
│ Release │
└──────────────┘
@objectstack/core
├── Responsibilities: 4
│ 1. Plugin Lifecycle ✅
│ 2. Logger Implementation ❌
│ 3. Contract Definitions ❌
│ 4. Plugin Loading ❌
├── Dependencies:
│ ├── @objectstack/spec
│ ├── pino (hard dependency) ❌
│ └── zod
└── Issues:
├── Too many concerns
├── Hard to test
└── Difficult to reuse
@objectstack/spec
├── Responsibilities: 1
│ 1. All Protocol Definitions ✅
├── New Exports:
│ └── /contracts (IServiceRegistry, IPluginValidator, etc.)
└── Dependencies:
└── zod only ✅
@objectstack/logger (NEW)
├── Responsibilities: 1
│ 1. Logging Implementation ✅
├── Dependencies:
│ └── pino (optional peer) ✅
└── Can be used standalone ✅
@objectstack/core
├── Responsibilities: 1
│ 1. Plugin Lifecycle Only ✅
├── Dependencies:
│ ├── @objectstack/spec (contracts)
│ ├── @objectstack/logger (injected)
│ └── zod
└── Issues:
✅ Single concern
✅ Easy to test
✅ Clean dependencies
- Code duplication < 5% (Currently: ~40%)
- Test coverage > 90% (Currently: ~70%)
- Cyclomatic complexity < 10 for all functions (Currently: some >15)
- All ESLint rules pass with no warnings
- All TypeScript strict mode enabled
- All contracts in
@objectstack/spec/contracts - Logger extracted to standalone package
- Core package has single responsibility
- All 7 core interfaces defined
- Zero circular dependencies (Currently: ✅ Already achieved)
- Kernel startup < 100ms (no plugins)
- Service lookup < 1μs
- Event trigger < 10μs
- Memory usage ≤ current version
- Build time unchanged or improved
- 100% API documentation coverage
- Complete migration guide published
- All examples updated
- Architecture diagrams updated
- Video tutorial created
Current Approach (Problematic):
// Two separate implementations with duplicate code
class ObjectKernel { /* 219 lines */ }
class EnhancedObjectKernel { /* 496 lines */ }
// Result: 40% duplication, hard to maintainSolution (Composition Pattern):
// Shared base class
abstract class ObjectKernelBase { /* 150 lines */ }
// Lightweight implementation
class ObjectKernel extends ObjectKernelBase { /* 100 lines */ }
// Enhanced via composition
class EnhancedObjectKernel extends ObjectKernelBase {
constructor(
validator: IPluginValidator,
orchestrator: IStartupOrchestrator,
lifecycle: IServiceLifecycleManager
) { /* 200 lines */ }
}
// Result: Zero duplication, easy to extendMissing Critical Interfaces:
-
IServiceRegistry - No standard service contract
- Impact: Cannot swap implementations
- Impact: Difficult to test (cannot mock)
-
IPluginValidator - Validation logic scattered
- Impact: Inconsistent validation paths
- Impact: Hard to add new validation rules
-
IStartupOrchestrator - Startup logic embedded in kernel
- Impact: Cannot test startup strategies independently
- Impact: Cannot add new orchestration patterns
-
IPluginLifecycleEvents - Untyped event system
- Impact: No compile-time type checking
- Impact: Easy to make mistakes in event names
Misplaced Components:
Logger in Core → Should be in @objectstack/logger
Why: Core should focus on plugin lifecycle, not logging
Impact: Tight coupling, hard to reuse logger elsewhere
Contracts in Core → Should be in @objectstack/spec
Why: Spec is the "source of truth" for all protocols
Impact: Violates "Protocol First" principle
PluginLoader too heavy → Should be split into 4 classes
Why: Single Responsibility Principle violation
Impact: Hard to test, hard to extend
- ✅ Review and approve optimization plan
- ✅ Create GitHub issues for each phase
- ✅ Set up project board for tracking
- ✅ Schedule kickoff meeting
- ✅ Create feature branch
refactor/microkernel-v1
- Create
packages/logger/structure - Define all 7 core interfaces in
spec/src/contracts/ - Set up CI/CD for new packages
- Write migration guide draft
- Create RFC for breaking changes
Follow the detailed development plan in:
- ARCHITECTURE-OPTIMIZATION.md (Chinese)
- ARCHITECTURE-OPTIMIZATION-EN.md (English)
- Executive Summary - Quick overview
- Detailed Analysis (Chinese) - Complete analysis in Chinese
- Detailed Analysis (English) - Complete analysis in English
- Current Architecture - Existing architecture documentation
- Package Dependencies - Dependency graph
Document Version: 1.0
Created: 2026-01-31
Status: Reference Document
Target Audience: Development Team, Technical Leads, Architects