glm-5.1
a2ee452a63
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.
6.6 KiB
6.6 KiB
status, last_updated
| status | last_updated |
|---|---|
| reviewed | 2026-05-30 |
@alkdev/storage Architecture
Typed graph storage with dual database hosts. Deno-first, published via JSR.
Current State
Storage has Phase 1-3 of the metagraph implementation complete: Metagraph Module, bridge functions, reference graph type Modules (CallGraph, SecretGraph), and crypto utility. Phase 4 (graphology bridge) is pending. The repository/CRUD layer, PostgreSQL host, and additional graph types remain to be implemented.
Architecture Documents
| Document | Content | Status |
|---|---|---|
| overview.md | Package purpose, exports, dependencies, ecosystem integration | reviewed |
| metagraph-module.md | TypeBox Module type system, bridge functions, implementation path | reviewed |
| sqlite-host.md | SQLite tables, relations, client factory, PG porting notes | reviewed |
| schema-evolution.md | Value.Diff/Cast/Patch for schema migration, version strategy | reviewed |
| encrypted-data.md | Crypto utility, encrypted node type, key management | reviewed |
| forward-look.md | Pointers, dbtype, ujsx IR (conceptual, post-v1) | draft |
Design Decisions
| ADR | Decision | Status |
|---|---|---|
| 001 | Deno-first, JSR publishes, npm comes free | Accepted |
| 002 | Metagraph pattern over domain-specific tables | Accepted |
| 003 | TypeBox Module as the graph type definition API surface | Accepted |
| 004 | Injectable clients, no module-level side effects | Accepted |
| 005 | Drizzle + TypeBox via drizzlebox | Accepted |
| 006 | as const objects, not TypeScript enums |
Accepted |
| 007 | No comments in code | Accepted |
| 008 | Common columns pattern | Accepted |
| 009 | TypeBox Module replaces the SchemaBuilder | Accepted |
| 010 | Metagraph.Import() for same-package Modules | Accepted |
| 011 | Config as Module entry with Literal values | Accepted |
| 012 | Node/edge attribute schemas are Module entries | Accepted |
| 013 | Storage produces graphology format, flowgraph consumes it | Accepted |
| 014 | Repository stores dereferenced entry schemas | Accepted |
| 015 | Edge type constraints as named Module entries | Accepted |
| 016 | Naming convention for Module entries | Accepted |
| 017 | Pointer abstraction is forward-looking, not v1 | Accepted |
| 018 | dbtype integration is post-v1 | Accepted |
| 019 | JSON text for schema columns in SQLite | Accepted |
| 020 | No nodeTypeId on nodes | Accepted |
| 021 | Edge identity uses consumer-defined keys | Accepted |
| 022 | Composite foreign keys for node references | Accepted |
| 023 | Per-attribute encryption, not per-node | Accepted |
| 024 | Encrypted data as node type, not standalone table | Accepted |
| 025 | Password-based encryption via PBKDF2 | Accepted |
| 026 | Application-managed key ring | Accepted |
| 027 | No key rotation utility in this package | Accepted |
| 028 | Additive-only for v1, Cast migration when needed | Accepted |
| 029 | Version as a coarse-grained breaking-change signal | Accepted |
| 030 | Schema change detection via Value.Diff | Accepted |
| 031 | moduleToDbSchema() for schema updates | Accepted |
| 032 | Single-author model, not CRDT | Accepted |
| 033 | JSON path queries and hand-written CRUD for v1 | Accepted |
Open Questions
All unresolved design questions are tracked in open-questions.md, organized by theme with cross-references between related questions.
Document Lifecycle
Architecture documents use YAML frontmatter with status and last_updated fields:
---
status: draft | reviewed | stable | deprecated
last_updated: YYYY-MM-DD
---
| Status | Meaning | Transitions |
|---|---|---|
draft |
Under active development. Content may change significantly. Implementation should not start until the document reaches reviewed. |
→ reviewed when all open questions are resolved and cross-cutting issues are addressed. |
reviewed |
Architecture is final and reviewed. Implementation may begin. API contracts are specified but not yet verified by tests. Changes require a review cycle. | → stable when implementation is complete and API contracts are verified by tests. → draft if a fundamental redesign is needed. |
stable |
API contracts are locked and verified by tests. Changes require a review cycle and may warrant an ADR. | → deprecated when superseded. |
deprecated |
Superseded by another document. Kept for reference. | Removed when no longer referenced. |
ADR documents use a separate Status field in their body: Proposed, Accepted, Deprecated, or Superseded. ADRs never revert from Accepted.
References
- Source:
src/ - AGENTS.md:
/workspace/@alkdev/storage/AGENTS.md - Flowgraph architecture (pattern reference):
/workspace/@alkdev/flowgraph/docs/architecture/ - ujsx architecture:
/workspace/@alkdev/ujsx/docs/architecture/ - Operations architecture:
/workspace/@alkdev/operations/docs/architecture/