glm-5.1
67ccfbf928
- Create decisions/ directory with 32 numbered ADRs (ADR-001 through ADR-032) extracted from inline DD/SD/ED/SE decision sections - Create open-questions.md with 16 OQs organized by theme, cross-referenced to ADRs, with status tracking (resolved/open) - Create README.md as architecture index with doc table, ADR table, and lifecycle status definitions (draft/reviewed/stable/deprecated) - Replace inline decision sections in all spec docs with ADR reference tables - Replace inline open questions with OQ references to centralized tracker - Update frontmatter: metagraph-module.md, overview.md, sqlite-host.md → reviewed; schema-evolution.md and encrypted-data.md remain draft - DD1-DD10 → ADR-009 through ADR-018 - D1-D8 → ADR-001 through ADR-008 - SD1-SD5 → ADR-019 through ADR-023 (SD5 folded into ADR-006/008) - ED1-ED5 → ADR-023 through ADR-027 - SE1-SE5 → ADR-028 through ADR-032
status, last_updated
| status | last_updated |
|---|---|
| reviewed | 2026-05-29 |
@alkdev/storage Architecture
Typed graph storage with dual database hosts. Deno-first, published via JSR.
Current State
Storage is in Phase 1/2 (SQLite tables and type system implemented; repository layer, tests, PostgreSQL host, and encrypted data not yet 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 | draft |
| encrypted-data.md | Crypto utility, encrypted node type, key management | draft |
| 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 |
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/