storage/docs/architecture/README.md

status, last_updated

status	last_updated
draft	2026-06-02

@alkdev/storage Architecture

Typed graph storage with SQLite via Honker. 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 package is transitioning to SQLite-only with Honker integration (ADR-038, ADR-039) and adding identity tables for multi-tenant support (ADR-041). The repository/CRUD layer, Drizzle-Honker adapter, identity tables, and additional graph types remain to be implemented.

Architecture Documents

Document	Content	Status
overview.md	Package purpose, exports, dependencies, database model, ecosystem integration	draft
metagraph-module.md	TypeBox Module type system, bridge functions, implementation path	reviewed
sqlite-host.md	SQLite tables (metagraph + identity), client factories, Honker adapter	draft
honker-integration.md	Drizzle-Honker adapter, event patterns, system/tenant DB coordination	draft
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
acl.md	Access control graph: principal/agent framework, scoping, operations integration	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
034	ACL is a metagraph, not domain-specific tables	Accepted
035	Actors become ACL nodes, standalone table removed	Accepted
036	Principal-agent as delegation edges with scope narrowing	Accepted
037	Setup-time definitions seed graph types, runtime instances are separate	Accepted
038	SQLite-first, Postgres removed	Accepted
039	Honker as SQLite extension and transport	Accepted
040	System DB + tenant DB separation	Accepted
041	Identity tables in storage package	Accepted
042	Scoping columns on graph instances	Accepted
043	Graph type scope — system/tenant/user	Accepted
044	Drizzle-Honker session adapter	Accepted
045	organization_members authoritative, BelongsToEdge derived	Accepted
046	Fold @alkdev/drizzlebox as src/sqlite/utils	Accepted
047	HonkerEventTarget adapter for pubsub	Accepted
048	OperationSpecs as repository surface	Accepted
049	Identity schema restructuring — separate credential tables, remove Gitea, data→metadata	Accepted
050	SHA-256 for machine-generated API keys	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
• Honker source: /workspace/honker/
• Flowgraph architecture: /workspace/@alkdev/flowgraph/docs/architecture/
• ujsx architecture: /workspace/@alkdev/ujsx/docs/architecture/
• Operations architecture: /workspace/@alkdev/operations/docs/architecture/