initial documentation

This is a high level description of what buckit is and how it works.

2 files changed, 63 insertions, 1 deletions

diff --git a/users/fcuny/exp/buckit/README.md b/users/fcuny/exp/buckit/README.md
deleted file mode 100644
index 963af94..0000000
--- a/users/fcuny/exp/buckit/README.md
+++ /dev/null
@@ -1 +0,0 @@
-# buckit
\ No newline at end of file
diff --git a/users/fcuny/exp/buckit/README.org b/users/fcuny/exp/buckit/README.org
new file mode 100644
index 0000000..d6ab4c5
--- /dev/null
+++ b/users/fcuny/exp/buckit/README.org
@@ -0,0 +1,63 @@
+#+TITLE: buckit
+
+~buckit~ is a tool to add files to a GCS bucket.
+
+* Store
+=buckit= is a CLI to upload files to a GCS bucket. A file belongs to a *namespace*. A namespace can have multiple *files*. Each files can have multiple *versions*.
+
+When a version of a file is added to a namespace, a record is created in the index.
+
+A record is composed of the following information:
+- the version of the file
+- the name of the file
+- the name of the namespace
+- the checksum of the version
+- the path in the GCS bucket
+- the user who uploaded the version
+- the timestamp of when the uploaded happened
+- the state of the file
+
+GCS' ACLs are used to change the visibility of the object in the bucket.
+
+The index is a single JSON file stored at the root of the bucket. The keys in the index are the namespace. Inside a namespace, keys are the name of the files. Files contain a list of versions, in order (the most recent version is the last entry in the list).
+
+A lock is used for both read and write of the file.
+** Life cycle of files
+*** Deletion
+By default, when a file is uploaded, we mark the state has *present*.
+
+Versions can be deleted. This is a soft-delete:
+- the state is changed to *tombstone*
+- the expiration date for blob is set 30 days in the future
+
+When a file is marked for deletion, it can not be fetched anymore. The state can be changed to be mark as present. In which case the expiration date is removed on the blob.
+* CLI
+** add
+#+begin_src sh
+buckit add <namespace> <file> <file path>
+#+end_src
+** list
+#+begin_src sh
+buckit list
+#+end_src
+
+#+begin_src sh
+buckit list <namespace>
+#+end_src
+** fetch
+#+begin_src sh
+buckit fetch <namespace> <file> <version>
+#+end_src
+** info
+#+begin_src sh
+buckit info <namespace> <file> <version>
+#+end_src
+** delete
+#+begin_src sh
+buckit delete <namespace> <file> <version>
+#+end_src
+** undelete
+#+begin_src sh
+bucket undelete <namespace> <file> <version>
+#+end_src
+