Add repository layer strategy: JSON path queries, CRUD decisions, ecosystem integration
Add three open questions (OQ-17, OQ-18, OQ-19) covering attribute query strategy, CRUD generation approach, and storage-operations bridge placement. Create ADR-033 recording the v1 decision: JSON path queries for attributes with hand-written CRUD for static tables. Expand forward-look.md with Repository Layer Strategy section analyzing three approaches (JSON path, native columns via dbtype, hybrid) and their implications for the metagraph pattern. Add drizzle-graphql and dbtype from-dbtype comparison showing neither handles dynamic schema-as-data. Update overview.md with dbtype/ujsx in the dependency diagram, expanded ecosystem context in the bridging pattern section, and new open questions. Align open-questions.md: resolve OQ-17 and OQ-18 for v1 (ADR-033), add OQ-19 as open, update summary counts and ADR impact table.
This commit is contained in:
@@ -90,6 +90,7 @@ All design decisions are documented as ADRs in [decisions/](decisions/).
|
||||
| [006](decisions/006-enum-pattern-as-const-objects.md) | `as const` objects, not TypeScript enums | Avoids JSR slow-types; consistent pattern across codebase |
|
||||
| [007](decisions/007-no-comments-in-code.md) | No comments in code | Documentation lives in architecture docs and TypeBox descriptions |
|
||||
| [008](decisions/008-common-columns-pattern.md) | Common columns pattern | `id`, `metadata`, `createdAt`, `updatedAt` on every table |
|
||||
| [033](decisions/033-json-path-queries-for-v1.md) | JSON path queries and hand-written CRUD for v1 | Attribute queries use JSON path; CRUD is hand-written; dbtype and auto-generation are post-v1 |
|
||||
|
||||
## Dependencies
|
||||
|
||||
@@ -152,6 +153,11 @@ and taskgraph) as part of its architecture.
|
||||
@alkdev/taskgraph ← task dependency graph schema, cost-benefit analysis
|
||||
(depends on: @alkdev/typebox)
|
||||
|
||||
@alkdev/dbtype ← schema-first multi-dialect DB type system (Phase 0, not yet implemented)
|
||||
(depends on: @alkdev/typebox, @alkdev/ujsx)
|
||||
Renders UJSX element trees to Drizzle dialects; future: from-dbtype
|
||||
adapter generates CRUD OperationSpecs for @alkdev/operations
|
||||
|
||||
@alkdev/storage ← YOU ARE HERE — typed graph persistence
|
||||
(depends on: @alkdev/typebox, @alkdev/drizzlebox)
|
||||
|
||||
@@ -177,6 +183,8 @@ define the semantics itself.
|
||||
| Call graph schema (`CallNodeAttrs`, `CallEdgeAttrs`, `CallStatus`) | `@alkdev/flowgraph` | Storage persists these in-memory shapes to the database |
|
||||
| Task graph schema (`TaskGraphNodeAttributes`, `DependencyEdge`) | `@alkdev/taskgraph` | Storage persists task dependency shapes |
|
||||
| Event transport (`TypedEventTarget`, `EventEnvelope`) | `@alkdev/pubsub` | Storage is not involved in event routing; it stores the events' outcomes |
|
||||
| Database schema rendering (`<table>`, `<column>`, HostConfig) | `@alkdev/dbtype` | Storage's static metagraph tables could be dbtype-rendered in the future (OQ-17, OQ-18) |
|
||||
| Universal IR (`h()`, `createComponent`, `createRoot`) | `@alkdev/ujsx` | Storage's `Type.Module` format is structurally compatible with ujsx rendering; no runtime dependency |
|
||||
|
||||
### Repository Layer Bridging Pattern (Consumer-Side Concern)
|
||||
|
||||
@@ -190,7 +198,8 @@ because:
|
||||
1. `@alkdev/operations` already maps closely to GraphQL's
|
||||
queries/mutations/subscriptions (it was modeled after that pattern)
|
||||
2. `@alkdev/pubsub` provides the subscription transport (forked from
|
||||
graphql-yoga's pubsub with additions)
|
||||
graphql-yoga's pubsub with additions like in-memory, Redis, WebSocket,
|
||||
WebWorker event targets)
|
||||
3. `@alkdev/storage`'s metagraph tables are the data source, analogous to
|
||||
Drizzle tables for drizzle-graphql
|
||||
|
||||
@@ -204,6 +213,32 @@ to avoid circular dependencies:
|
||||
Consumer (hub / adapter) → imports both, generates operations from schemas
|
||||
```
|
||||
|
||||
#### Ecosystem Context
|
||||
|
||||
The question of *where* this bridge lives and *how* it's generated connects to
|
||||
the broader ecosystem:
|
||||
|
||||
- **drizzle-graphql** (`/workspace/drizzle-graphql`): Auto-generates GraphQL
|
||||
CRUD from Drizzle tables. The reference pattern for "database schema → API
|
||||
surface." Produces `{ schema, entities }` from `buildSchema(db)`. No TypeBox,
|
||||
no metagraph.
|
||||
|
||||
- **@alkdev/dbtype**: Schema-first multi-dialect system using ujsx element trees.
|
||||
Defines `<table>`, `<column>` elements rendered to Drizzle via HostConfig. Has
|
||||
a designed `from-dbtype` adapter that generates `OperationSpec[]` from element
|
||||
trees + Type.Module bundles. Phase 0 (architecture only, no implementation).
|
||||
|
||||
- **@alkdev/operations**: Runtime-agnostic typed operations registry with
|
||||
adapters (`FromOpenAPI`, `from_mcp`, `from_typemap`) that generate
|
||||
`OperationSpec[]` from external specifications. The `from-dbtype` adapter would
|
||||
be another adapter in the same pattern.
|
||||
|
||||
The strategic question (OQ-17, OQ-18) is whether storage's repository CRUD
|
||||
operations should be hand-written, auto-generated from Drizzle schemas, or
|
||||
auto-generated from dbtype element trees once dbtype is implemented. For v1,
|
||||
hand-written CRUD is the simplest path and doesn't block any long-term option.
|
||||
See [forward-look.md](forward-look.md) for the full analysis.
|
||||
|
||||
### Avoiding Circular Dependencies
|
||||
|
||||
Neither `@alkdev/storage` nor `@alkdev/operations` should depend on each
|
||||
@@ -229,6 +264,9 @@ questions affecting this package:
|
||||
- **OQ-14**: Should encryption be per-attribute, per-node, or per-graph? (resolved: per-attribute)
|
||||
- **OQ-15**: Should key management be in this package? (resolved: no, application provides key ring)
|
||||
- **OQ-16**: Should the repository layer live in storage or a consumer package? (resolved: CRUD in storage, operations bridging in consumer)
|
||||
- **OQ-17**: How should the repository layer handle attribute queries — JSON path, native columns, or dbtype-generated? (open, JSON path for v1)
|
||||
- **OQ-18**: Should CRUD operations be auto-generated or hand-written? (open, hand-write for v1)
|
||||
- **OQ-19**: Where does the storage-operations bridge package live? (open, depends on OQ-17/OQ-18)
|
||||
|
||||
## References
|
||||
|
||||
|
||||
Reference in New Issue
Block a user