storage/docs/architecture/README.md

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/