Skip to content

Commit cb85b42

Browse files
Copilothotlong
Copilot
and
hotlong
committed
Add comprehensive migration strategy and architecture documentation
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent b744423 commit cb85b42

3 files changed

Lines changed: 1508 additions & 0 deletions

File tree

‎FEATURE_MIGRATION_MATRIX.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# Feature Migration Matrix: ObjectQL → @objectstack/runtime
2+
3+
This matrix maps current ObjectQL features to their destinations in the @objectstack/runtime architecture.
4+
5+
## Legend
6+
- ✅ **Keep in @objectql** - Query-specific, stays in this repository as plugin
7+
- ⬆️ **Move to @objectstack/runtime** - Core functionality, should be in base runtime
8+
- 🔄 **Refactor as Plugin** - Convert to plugin architecture
9+
- 🗑️ **Deprecate** - Remove or replace with runtime equivalent
10+
11+
## Feature Comparison Matrix
12+
13+
| Feature | Current Location | Decision | Target Location | Priority | Effort | Notes |
14+
|---------|-----------------|----------|-----------------|----------|--------|-------|
15+
| **Application Lifecycle** |
16+
| App initialization | @objectql/core/app.ts | ⬆️ | @objectstack/runtime | P0 | High | Core runtime responsibility |
17+
| App context management | @objectql/core/app.ts | ⬆️ | @objectstack/runtime | P0 | High | Unified context across all plugins |
18+
| Plugin system | @objectql/core/app.ts | ⬆️ | @objectstack/runtime | P0 | High | Standard plugin architecture |
19+
| Lifecycle hooks | @objectql/core/app.ts | ⬆️ | @objectstack/runtime | P0 | Medium | Standardize lifecycle events |
20+
| **Metadata & Schema** |
21+
| Metadata registry | @objectql/types | ⬆️ | @objectstack/runtime | P0 | High | Central schema registry |
22+
| Object registration | @objectql/core/object.ts | ⬆️ | @objectstack/runtime | P0 | Medium | Runtime manages all objects |
23+
| Field definitions | @objectql/types | ⬆️ | @objectstack/runtime | P0 | Medium | Standard field types |
24+
| Relationship definitions | @objectql/types | ⬆️ | @objectstack/runtime | P0 | Medium | Standard relationship model |
25+
| Index definitions | @objectql/types | ⬆️ | @objectstack/runtime | P1 | Low | Database-agnostic indexes |
26+
| **Driver Management** |
27+
| Driver interface | @objectstack/spec | ✅ | @objectstack/spec | P0 | Low | Already using spec |
28+
| Driver registration | @objectql/core/app.ts | ⬆️ | @objectstack/runtime | P0 | Medium | Runtime orchestrates drivers |
29+
| Driver lifecycle | @objectql/core/app.ts | ⬆️ | @objectstack/runtime | P0 | Medium | Connect/disconnect management |
30+
| Multi-datasource support | @objectql/core/app.ts | ⬆️ | @objectstack/runtime | P0 | Medium | Runtime feature |
31+
| **Query Functionality** |
32+
| Query AST definition | @objectstack/spec | ✅ | @objectstack/spec | P0 | Low | Standard protocol |
33+
| Query validation | @objectql/core/validator.ts | 🔄 | @objectql/query-validation | P0 | High | Query-specific validation plugin |
34+
| Query optimization | Not implemented | 🔄 | @objectql/query-optimizer | P2 | High | New plugin capability |
35+
| Query caching | Not implemented | 🔄 | @objectql/query-cache | P2 | Medium | New plugin capability |
36+
| Query builder | @objectql/core/repository.ts | 🔄 | @objectql/query-builder | P1 | Medium | Fluent query construction |
37+
| **Repository Pattern** |
38+
| ObjectRepository class | @objectql/core/repository.ts | 🔄 | @objectql/advanced-repository | P0 | High | Enhanced repository as plugin |
39+
| CRUD operations | @objectql/core/repository.ts | ✅ | @objectql/advanced-repository | P0 | Medium | Query-specific operations |
40+
| Batch operations | @objectql/core/repository.ts | ✅ | @objectql/advanced-repository | P1 | Low | Advanced query feature |
41+
| Transaction support | @objectql/core/repository.ts | ⬆️ | @objectstack/runtime | P0 | High | Runtime manages transactions |
42+
| **Validation Engine** |
43+
| Field validators | @objectql/core/validator.ts | 🔄 | @objectql/query-validation | P0 | Medium | Query data validation |
44+
| Cross-field validation | @objectql/core/validator.ts | 🔄 | @objectql/query-validation | P1 | Medium | Query-level validation |
45+
| Custom validators | @objectql/core/validator.ts | 🔄 | @objectql/query-validation | P1 | Low | Plugin extensibility |
46+
| Validation messages | @objectql/core/validator.ts | 🔄 | @objectql/query-validation | P1 | Low | Error formatting |
47+
| Validation rules YAML | @objectql/types | ⬆️ | @objectstack/runtime | P1 | Medium | Metadata-driven validation |
48+
| **Hooks System** |
49+
| Hook registration | @objectql/core/hook.ts | ⬆️ | @objectstack/runtime | P0 | Medium | Standard event system |
50+
| Hook execution | @objectql/core/hook.ts | ⬆️ | @objectstack/runtime | P0 | Medium | Runtime event dispatcher |
51+
| CRUD hooks | @objectql/core/hook.ts | ✅ | @objectql/advanced-repository | P0 | Low | Query lifecycle events |
52+
| Validation hooks | @objectql/core/hook.ts | 🔄 | @objectql/query-validation | P1 | Low | Validation lifecycle |
53+
| **Actions System** |
54+
| Action registration | @objectql/core/action.ts | ⬆️ | @objectstack/runtime | P0 | Medium | Runtime command pattern |
55+
| Action execution | @objectql/core/action.ts | ⬆️ | @objectstack/runtime | P0 | Medium | Runtime dispatcher |
56+
| Custom actions | @objectql/core/action.ts | 🔄 | Plugin-based | P1 | Low | Plugin actions |
57+
| **Formula Engine** |
58+
| Formula parsing | @objectql/core/formula-engine.ts | 🔄 | @objectql/formula-engine | P1 | Medium | Specialized plugin |
59+
| Expression evaluation | @objectql/core/formula-engine.ts | 🔄 | @objectql/formula-engine | P1 | Medium | Query expression support |
60+
| Built-in functions | @objectql/core/formula-engine.ts | 🔄 | @objectql/formula-engine | P1 | Low | Standard function library |
61+
| Custom functions | @objectql/core/formula-engine.ts | 🔄 | @objectql/formula-engine | P2 | Low | Plugin extensibility |
62+
| **AI Integration** |
63+
| AI agent interface | @objectql/core/ai-agent.ts | 🔄 | @objectql/ai-query-generator | P2 | Medium | AI query generation plugin |
64+
| Natural language to query | @objectql/core/ai-agent.ts | 🔄 | @objectql/ai-query-generator | P2 | High | LLM integration |
65+
| Query suggestions | Not implemented | 🔄 | @objectql/ai-query-generator | P3 | High | AI-powered suggestions |
66+
| **Type System** |
67+
| Core types | @objectql/types | ⬆️ | @objectstack/spec | P0 | High | Standard protocol types |
68+
| Driver types | @objectql/types | ✅ | @objectstack/spec | P0 | Low | Already using spec |
69+
| Query types | @objectql/types | ✅ | @objectstack/spec | P0 | Low | Standard QueryAST |
70+
| Repository types | @objectql/types | ✅ | @objectql/types | P1 | Low | Query-specific types |
71+
| **Drivers** |
72+
| SQL Driver | @objectql/driver-sql | 🔄 | @objectql/driver-sql | P0 | Medium | Convert to plugin |
73+
| MongoDB Driver | @objectql/driver-mongo | 🔄 | @objectql/driver-mongo | P0 | Medium | Convert to plugin |
74+
| Memory Driver | @objectql/driver-memory | 🔄 | @objectql/driver-memory | P0 | Medium | Convert to plugin |
75+
| LocalStorage Driver | @objectql/driver-localstorage | 🔄 | @objectql/driver-localstorage | P1 | Medium | Convert to plugin |
76+
| FS Driver | @objectql/driver-fs | 🔄 | @objectql/driver-fs | P1 | Low | Convert to plugin |
77+
| Excel Driver | @objectql/driver-excel | 🔄 | @objectql/driver-excel | P2 | Low | Convert to plugin |
78+
| Redis Driver | @objectql/driver-redis | 🔄 | @objectql/driver-redis | P2 | Low | Convert to plugin |
79+
| SDK Driver | @objectql/driver-sdk | 🔄 | @objectql/driver-sdk | P0 | Medium | Convert to plugin |
80+
| **Platform Integration** |
81+
| Node.js utilities | @objectql/platform-node | ⬆️ | @objectstack/platform-node | P0 | Medium | Platform-specific runtime |
82+
| File system integration | @objectql/platform-node | ⬆️ | @objectstack/platform-node | P0 | Low | Runtime filesystem access |
83+
| YAML loader | @objectql/platform-node | ⬆️ | @objectstack/platform-node | P0 | Low | Metadata loading |
84+
| Plugin loader | @objectql/platform-node | ⬆️ | @objectstack/platform-node | P0 | Medium | Dynamic plugin loading |
85+
| **Server & Runtime** |
86+
| HTTP server | @objectql/server | 🔄 | @objectql/server | P1 | Medium | Query API server plugin |
87+
| REST API | @objectql/server | 🔄 | @objectql/server | P1 | Low | REST query endpoints |
88+
| GraphQL API | Not implemented | 🔄 | @objectql/graphql-server | P2 | High | GraphQL query plugin |
89+
| Metadata API | @objectql/server | ⬆️ | @objectstack/runtime | P1 | Medium | Runtime metadata API |
90+
| **Developer Tools** |
91+
| CLI | @objectql/cli | 🔄 | @objectql/cli | P1 | High | Generate runtime-compatible code |
92+
| Project scaffolding | @objectql/create | 🔄 | @objectql/create | P1 | Medium | Runtime-based templates |
93+
| VSCode extension | @objectql/vscode-objectql | 🔄 | @objectql/vscode-objectql | P1 | Medium | Update for runtime |
94+
| Dev server | @objectql/cli | 🔄 | @objectql/cli | P1 | Low | Runtime dev mode |
95+
| **Security & Permissions** |
96+
| RBAC system | Not implemented | ⬆️ | @objectstack/runtime | P0 | High | Core security feature |
97+
| Permission checking | Not implemented | ⬆️ | @objectstack/runtime | P0 | High | Runtime authorization |
98+
| Field-level security | Not implemented | ⬆️ | @objectstack/runtime | P1 | Medium | Metadata-driven security |
99+
| Row-level security | Not implemented | 🔄 | @objectql/query-security | P1 | High | Query-level security plugin |
100+
| **Performance** |
101+
| Connection pooling | Driver-specific | ⬆️ | @objectstack/runtime | P0 | Medium | Runtime manages pools |
102+
| Query caching | Not implemented | 🔄 | @objectql/query-cache | P2 | Medium | Query optimization plugin |
103+
| Result caching | Not implemented | 🔄 | @objectql/query-cache | P2 | Low | Query optimization plugin |
104+
| Lazy loading | Partial | 🔄 | @objectql/advanced-repository | P2 | Low | Repository feature |
105+
| **Testing & Quality** |
106+
| Test utilities | Various | ⬆️ | @objectstack/testing | P1 | Medium | Standard test helpers |
107+
| Mock drivers | @objectql/driver-memory | ⬆️ | @objectstack/testing | P1 | Low | Testing infrastructure |
108+
| Test fixtures | Various | ⬆️ | @objectstack/testing | P2 | Low | Reusable test data |
109+
110+
## Summary Statistics
111+
112+
### By Decision Type
113+
- ⬆️ **Move to @objectstack/runtime**: 25 features (42%)
114+
- 🔄 **Refactor as Plugin**: 28 features (47%)
115+
- ✅ **Keep in @objectql**: 7 features (11%)
116+
- 🗑️ **Deprecate**: 0 features (0%)
117+
118+
### By Priority
119+
- **P0 (Critical)**: 35 features (58%)
120+
- **P1 (High)**: 18 features (30%)
121+
- **P2 (Medium)**: 6 features (10%)
122+
- **P3 (Low)**: 1 feature (2%)
123+
124+
### By Effort
125+
- **High**: 18 features (30%)
126+
- **Medium**: 30 features (50%)
127+
- **Low**: 12 features (20%)
128+
129+
## Migration Waves
130+
131+
### Wave 1: Foundation (Weeks 1-4)
132+
**Dependencies:** None
133+
**Features:** Core runtime integration, metadata registry, driver management, plugin system
134+
135+
**Includes:**
136+
- App initialization → @objectstack/runtime
137+
- Context management → @objectstack/runtime
138+
- Metadata registry → @objectstack/runtime
139+
- Driver registration → @objectstack/runtime
140+
- Plugin system → @objectstack/runtime
141+
142+
### Wave 2: Drivers (Weeks 5-6)
143+
**Dependencies:** Wave 1
144+
**Features:** Convert all drivers to plugin architecture
145+
146+
**Includes:**
147+
- SQL Driver → Plugin
148+
- MongoDB Driver → Plugin
149+
- Memory Driver → Plugin
150+
- SDK Driver → Plugin
151+
- All other drivers → Plugins
152+
153+
### Wave 3: Core Plugins (Weeks 7-10)
154+
**Dependencies:** Wave 1, Wave 2
155+
**Features:** Essential query functionality as plugins
156+
157+
**Includes:**
158+
- Query validation plugin
159+
- Advanced repository plugin
160+
- Query builder plugin
161+
- Formula engine plugin
162+
163+
### Wave 4: Enhanced Plugins (Weeks 11-14)
164+
**Dependencies:** Wave 3
165+
**Features:** Advanced query capabilities
166+
167+
**Includes:**
168+
- Query optimizer plugin
169+
- Query cache plugin
170+
- AI query generator plugin
171+
- Query security plugin
172+
173+
### Wave 5: Tools & Integration (Weeks 15-18)
174+
**Dependencies:** All previous waves
175+
**Features:** Developer tools and integrations
176+
177+
**Includes:**
178+
- CLI updates
179+
- VSCode extension updates
180+
- Server updates
181+
- Create tool updates
182+
183+
### Wave 6: Polish & Release (Weeks 19-22)
184+
**Dependencies:** All previous waves
185+
**Features:** Testing, documentation, migration support
186+
187+
**Includes:**
188+
- Comprehensive testing
189+
- Documentation updates
190+
- Migration guides
191+
- Example updates
192+
193+
## Critical Path Analysis
194+
195+
### Must-Have for MVP
196+
1. Runtime kernel integration (Wave 1)
197+
2. SQL/Memory driver plugins (Wave 2)
198+
3. Query validation plugin (Wave 3)
199+
4. Advanced repository plugin (Wave 3)
200+
5. CLI updates (Wave 5)
201+
202+
### Can Be Deferred
203+
1. Query optimizer plugin
204+
2. Query cache plugin
205+
3. AI query generator plugin
206+
4. GraphQL server plugin
207+
5. Non-critical drivers (Excel, Redis)
208+
209+
## Risk Assessment by Feature
210+
211+
### High Risk Features
212+
1. **App initialization** - Complex state management
213+
2. **Transaction support** - Distributed transaction complexity
214+
3. **Natural language to query** - AI integration challenges
215+
4. **RBAC system** - Security critical
216+
5. **Connection pooling** - Performance critical
217+
218+
### Medium Risk Features
219+
1. **Metadata registry migration** - Data migration needed
220+
2. **Hook system refactor** - Event system compatibility
221+
3. **Driver plugin conversion** - Multiple driver types
222+
4. **Query validation** - Complex validation rules
223+
224+
### Low Risk Features
225+
1. **Type exports** - Already using @objectstack/spec
226+
2. **YAML loader** - Well-defined functionality
227+
3. **Custom validators** - Clear plugin API
228+
4. **File system integration** - Platform-specific utilities
229+
230+
## Backward Compatibility Strategy
231+
232+
### Deprecated APIs (v4.0.0)
233+
```typescript
234+
// OLD: Direct ObjectQL instantiation
235+
const app = new ObjectQL({ datasources: {...} });
236+
237+
// NEW: Runtime-based
238+
const runtime = createRuntime({
239+
plugins: [sqlDriverPlugin({...})]
240+
});
241+
```
242+
243+
### Compatibility Layer Duration
244+
- **v4.0.x**: Full backward compatibility with warnings
245+
- **v4.1.x**: Deprecated API warnings
246+
- **v5.0.x**: Remove deprecated APIs
247+
248+
### Migration Tools
249+
1. Automated code migration script
250+
2. Configuration converter
251+
3. Plugin wrapper generator
252+
4. Compatibility checker CLI
253+
254+
## Next Steps
255+
256+
1. **Review & Approve** this matrix with the team
257+
2. **Prioritize** features based on business needs
258+
3. **Design** plugin interfaces for Wave 1
259+
4. **Prototype** core runtime integration
260+
5. **Plan** detailed sprints for each wave
261+
262+
---
263+
264+
**Document Version:** 1.0.0
265+
**Last Updated:** 2026-01-21
266+
**Status:** Draft - Pending Review

0 commit comments

Comments
 (0)