Rewrite "How data is stored" -> "Modules"

1 files changed, 52 insertions, 15 deletions

diff --git a/README.md b/README.md
index 917c8b9e..100e8da7 100644
--- a/README.md
+++ b/README.md
@@ -3,31 +3,68 @@
 Imag is a CLI PIM suite with a nice API-ish commandline interface, so you can
 integrate it in your tools of coice (Editor, MUA, RSS reader, etc etc).
 
-## How data is stored
+## Modules
 
-The backends define how the data is stored and accessed. Each backend has
-either Read-Write permission or Read-Only.
+All the modules have access to a shared store (which lives in `~/.imag/store/`
+by default). Files are named after a schema:
 
-By now, only files are planned as storage backend.
+    ~/.imag/store/<module_name>-<hashtype>-<hash>.imag
 
-File formats are
+Where module name is "bookmark" for example. The hashtype is "UUID" by default
+and the "hash" is a UUID then. Other types are possible as well:
 
-* JSON
-* Markdown with YAML-Header
+- SHA1
+- SHA512
 
-## Tools
+for example (though it might not be a good idea to use SHA hashes,
+see [Linking](#Linking))
 
-Each tool has a storage "pool", which can be git version controlled. This can
-then be used to sync devices. For example bookmarks should be git version
-control, while mails should obviously not (they should also only be accessed
-RO).
+Some modules might not want to store content there, for example you don't want
+to put your icalendar files in there. So the calendar module just crawls through
+your ical files and puts the scanned meta-information into the store. Of course,
+if the content of the ical file changes, the store entry does not. It still
+points (via its JSON content for example) to the same file. So changes are not
+tracked (We can argue here whether we want to copy the contents to the store for
+ical and vcard files, but we cannot argue on for example music files).
+
+If a (for example ical-)file gets removed, the store entry gets invalid and has
+to be garbage-collected.
+
+>   The current model is not fixed yet. I'm thinking about copying .ical and
+>   .vcard, basically all text files, to the store.
+>   This is not possible for media files like music or movies, though. Also this
+>   is not feasible for documents like .pdf or similar.
 
 Each of the following modules has a short description including a table what
 core features are required to get it working.
 
-Note that all SHA512 hashes which appear in the following chapters are
-constants and they should never change. Changing them would break things, as
-the SHA512 hashes are used to be able to link data together.
+### Linking
+
+The UUID/SHA hashes in the file names can be used to connect two store entries.
+For example, an entry from the wiki could refer to a contact by a UUID, because
+the file for the contact has a UUID in its name. These UUIDs are constant and
+should not change.
+
+A link chain like this
+
+    Wiki -> Shopping List -> Calendar Entry
+            |                       |
+            |                       v
+            |                       Contact -> Calendar Entry -> Bookmark
+            v
+            Wiki Entry -> Bookmark
+
+is totally possible. Scenario: You have a Wiki entry of a recipe you like to
+cook. The recipe is linked to a shopping list, where you want to buy the
+ingredients. Of course, you want to do this on a specific date (calendar entry).
+And you want to do this with your Girlfriend, so she (as a contact) is linked to
+the calendar entry. Her Birthday is linked to her Contact and for her Birthday,
+you saw something on amazon, so you bookmarked it and linked it to the calendar
+entry.
+On the other hand, the Shopping list has links to some other Wiki entry, because
+it contains Kiwi, and you have notes about Kiwi, how to cook them properly. You
+saw this on some website, so you linked to the website from your wiki entry, of
+course.
 
 ### Bookmarks