Skip to content

Commit 5ae9ba8

Browse files
Copilothotlong
Copilot
and
hotlong
committed
docs: add architecture overview guide and update roadmap status
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent 7a1fa19 commit 5ae9ba8

3 files changed

Lines changed: 166 additions & 2 deletions

File tree

‎content/docs/guides/architecture.mdx‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
---
2+
title: "Architecture Overview"
3+
description: "Understanding ObjectQL's layered architecture — Types, Core, Platform, Drivers, and Protocols"
4+
---
5+
6+
# Architecture Overview
7+
8+
ObjectQL follows a strict **layered architecture** that enforces unidirectional dependencies, prevents circular imports, and keeps the type system as the single source of truth. Every package belongs to one of four layers.
9+
10+
## High-Level Architecture
11+
12+
```
13+
┌─────────────────────────────────────────────────────────────────┐
14+
│ Tools & DX │
15+
│ CLI · VSCode Extension · create-objectql │
16+
└──────────────────────────┬──────────────────────────────────────┘
17+
│ uses
18+
┌──────────────────────────▼──────────────────────────────────────┐
19+
│ Protocols │
20+
│ GraphQL · OData V4 · JSON-RPC · Sync Protocol │
21+
└──────────────────────────┬──────────────────────────────────────┘
22+
│ uses
23+
┌──────────────────────────▼──────────────────────────────────────┐
24+
│ Drivers │
25+
│ SQL · MongoDB · Redis · Memory · Excel · FS · PG-WASM · SQLite │
26+
└──────────────────────────┬──────────────────────────────────────┘
27+
│ implements
28+
┌──────────────────────────▼──────────────────────────────────────┐
29+
│ Foundation Layer │
30+
│ │
31+
│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────────┐ │
32+
│ │ Types │◄──│ Core │◄──│ Platform-Node │ │
33+
│ │ (Zero Deps) │ │ (Engine) │ │ (Node.js Bridge) │ │
34+
│ └─────────────┘ └─────────────┘ └──────────────────────┘ │
35+
│ │
36+
│ Plugins: Formula · Validator · Security · Multitenancy · Sync │
37+
└─────────────────────────────────────────────────────────────────┘
38+
```
39+
40+
## Layer 1: Foundation
41+
42+
The Foundation layer is the architectural core, following the **Trinity Architecture** pattern.
43+
44+
### @objectql/types — "The Constitution"
45+
46+
The single source of truth for all TypeScript interfaces, enums, and custom errors. This package has **zero production dependencies** and must never import from any sibling `@objectql/*` package.
47+
48+
Key exports include object/field definitions, query and filter types, driver abstractions, validation rules, hook interfaces, and the `ObjectQLError` class.
49+
50+
```typescript
51+
import { ObjectConfig, FieldConfig, ValidationRule } from '@objectql/types';
52+
```
53+
54+
### @objectql/core — "The Runtime Engine"
55+
56+
Implements the ORM kernel: `ObjectQL` class, `Validator`, `ObjectRepository`, formula engine, metadata registry, and query compilation. The core is **platform-agnostic** — it contains no Node.js native modules.
57+
58+
```typescript
59+
import { ObjectQL, Validator, SchemaRegistry } from '@objectql/core';
60+
```
61+
62+
### @objectql/platform-node — "The Node.js Bridge"
63+
64+
Bridges the platform-agnostic core to Node.js via file system access (`fs`, `path`, `glob`), YAML loading, and plugin discovery. Use this package only in Node.js server environments.
65+
66+
```typescript
67+
import { ObjectLoader } from '@objectql/platform-node';
68+
```
69+
70+
### Foundation Plugins
71+
72+
Core behavior is extended through plugins that depend only on `@objectql/types` and `@objectql/core`:
73+
74+
| Plugin | Purpose |
75+
|--------|---------|
76+
| `plugin-formula` | Computed fields and dynamic formulas |
77+
| `plugin-validator` | Metadata-driven validation engine |
78+
| `plugin-security` | RBAC, field masking, row-level security |
79+
| `plugin-multitenancy` | Tenant isolation and routing |
80+
| `plugin-sync` | Offline-first mutation logging and conflict resolution |
81+
82+
## Layer 2: Drivers
83+
84+
Drivers implement the `DriverInterface` defined in `@objectql/types`. Each driver translates abstract query ASTs into database-specific operations. Drivers depend on **types only** — never on core.
85+
86+
| Driver | Backend | Environment |
87+
|--------|---------|-------------|
88+
| `driver-sql` | PostgreSQL, MySQL, SQLite via Knex | Node.js |
89+
| `driver-mongo` | MongoDB | Node.js |
90+
| `driver-redis` | Redis | Node.js |
91+
| `driver-memory` | In-memory (Mingo) | Universal |
92+
| `driver-excel` | XLSX files | Node.js |
93+
| `driver-fs` | JSON/YAML files | Node.js |
94+
| `driver-pg-wasm` | PostgreSQL via WASM | Browser |
95+
| `driver-sqlite-wasm` | SQLite via WASM | Browser |
96+
97+
## Layer 3: Protocols
98+
99+
Protocols expose ObjectQL operations over network transports. They depend on **types + core**.
100+
101+
| Protocol | Transport | Compliance |
102+
|----------|-----------|------------|
103+
| `protocol-graphql` | HTTP (Query/Mutation) | 85% |
104+
| `protocol-odata-v4` | HTTP (REST) | 80% |
105+
| `protocol-json-rpc` | HTTP / WebSocket | 90% |
106+
| `protocol-sync` | HTTP / WebSocket | Sync protocol |
107+
108+
## Layer 4: Tools & DX
109+
110+
Developer-facing tools that consume all lower layers:
111+
112+
- **`@objectql/cli`** — Project scaffolding, code generation, migrations, REPL
113+
- **`@objectql/create`** — `npm create objectql` initializer
114+
- **`vscode-objectql`** — Schema validation, IntelliSense, snippets
115+
116+
## Dependency Flow
117+
118+
Dependencies flow strictly **downward**. No package may import from a package in the same or higher layer.
119+
120+
```
121+
Types ← Core ← Platform-Node
122+
↑ ↑
123+
│ └──── Protocols
124+
│
125+
└──────────── Drivers
126+
```
127+
128+
| Package | May Import From |
129+
|---------|-----------------|
130+
| `@objectql/types` | Nothing (`@objectstack/spec` for type derivation only) |
131+
| `@objectql/core` | `@objectql/types`, `@objectstack/*` runtime packages |
132+
| Drivers | `@objectql/types` |
133+
| Protocols | `@objectql/types`, `@objectql/core` |
134+
| Platform-Node | `@objectql/types`, `@objectql/core` |
135+
| Tools | Any lower layer |
136+
137+
## ObjectStack Kernel Integration
138+
139+
ObjectQL plugs into the broader **ObjectStack** ecosystem through the kernel pattern. The `ObjectStackKernel` boots applications, plugins, and drivers from declarative configuration manifests:
140+
141+
```typescript
142+
import { ObjectStackKernel } from '@objectstack/runtime';
143+
import { InMemoryDriver } from '@objectstack/driver-memory';
144+
145+
const kernel = new ObjectStackKernel([
146+
AppManifest,
147+
new InMemoryDriver(),
148+
]);
149+
150+
await kernel.start();
151+
```
152+
153+
The kernel handles lifecycle management, dependency injection, and plugin coordination — keeping ObjectQL's core engine focused purely on data operations.
154+
155+
## Next Steps
156+
157+
- **[Foundation Deep Dive](/docs/architecture)** — Trinity Architecture details and code examples
158+
- **[Error Handling Guide](/docs/guides/error-handling)** — `ObjectQLError` patterns and error codes
159+
- **[Driver Development](/docs/extending/custom-drivers)** — Implementing a custom driver

‎content/docs/guides/meta.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"title": "Guides",
33
"pages": [
4-
"error-handling"
4+
"error-handling",
5+
"architecture"
56
]
67
}

‎docs/ROADMAP_NEXT_PHASE.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ObjectQL — Next Phase Optimization & Improvement Roadmap
22

3-
> Created: 2026-02-09 | Status: **In Progress — Phases 1, 3, 4 (Wave 1-2), 5A, 6 (partial), 7 (partial) Complete**
3+
> Created: 2026-02-09 | Status: **In Progress — Phases 1A, 3, 4 (All Waves), 5A, 6, 7 (partial) Complete**
44
> Current Version: **4.2.0** | @objectstack Platform: **v2.0.1**
55
> Scope: Code quality, type safety, error handling, testing, performance, and DX improvements
66
@@ -457,6 +457,10 @@ Phase 6 (Documentation) ────────┐ Depends on Phase 5 (protoc
457457
Phase 7 (Performance) ────────┘ Independent, can start earlier
458458
```
459459

460+
> ✅ **Completed**: Phases 1A, 3, 4 (all waves), 5A, 6 (error-handling + architecture guides)
461+
> ✅ **Completed (partial)**: Phase 2 (create tests), Phase 7 (sideEffects)
462+
> ⏳ **Remaining**: Phase 1B (any reduction), Phase 5B (protocol refinement), Phase 7 (benchmarks)
463+
460464
### E. Risk Assessment
461465

462466
| Risk | Likelihood | Impact | Mitigation |

0 commit comments

Comments
 (0)