add some internal documentation

2 files changed, 36 insertions, 0 deletions

diff --git a/API b/API
new file mode 100644
index 0000000..f91e750
--- /dev/null
+++ b/API
@@ -0,0 +1,28 @@
+
+- instances (verbs)
+- objects (nouns)
+- sentence = verb + nouns
+
+=> separate documents from session information
+
+generic data store, convention for how entries look like
+distinguish records by type
+records have metadata and optionally data
+
+- create(metadata, data):
+  - add new entry, assign ids
+  - data='' indicates no data to store
+  - bad design? (data OOB)
+
+- add_version(tree_id, parent_id, metadata, data)
+  - add new version to existing object
+
+- change_metadata(tree_id, version_id, metadata)
+  - change the metadata of an existing version
+
+- restore(tree_id, parent_id, version_id, metadata, data)
+  - add a new version with the given ids
+  - there must be no existing entry with the same (tree_id, version_id)
+  - if parent_id != '' there must be an existing entry (tree_id, parent_id)
+  - if parent_id = '', there must be no existing entry with the same tree_id and no parent_id
+
diff --git a/STORAGE b/STORAGE
new file mode 100644
index 0000000..b48e30e
--- /dev/null
+++ b/STORAGE
@@ -0,0 +1,8 @@
+
+data -> tree, identified by checksum
+metadata -> tree, identified by checksum
+data + metadata -> tree, identified by checksum
+
+data + metadata reference -> commit, identified by checksum
+version -> branch HEAD, identified by version_id (as branch name)
+