5 files changed, 115 insertions, 51 deletions

diff --git a/docs/applicationdomaintypes.md b/docs/applicationdomaintypes.md
new file mode 100644
index 0000000..b0097a6
--- /dev/null
+++ b/docs/applicationdomaintypes.md
@@ -0,0 +1,86 @@
+## Domain Types
+A set of standardized domain types is defined. This is necessary to decouple applications from resources (so a calendar can access events from all resources), and to have a "language" for queries.
+
+The definition of the domain model directly affects:
+* granularity for data retrieval (email property, or individual subject, date, ...)
+* queriable properties for filtering and sorting (sender, id, ...)
+
+The purpose of these domain types is strictly to be the interface and the types are not meant to be used by applications directly, or to be restricted by any other specifications (such as ical). By nature these types will be part of the evolving interface, and will need to be adjusted for every new property that an application accesses.
+
+### Application Domain Types
+This is a proposed set of types that we will need to evolve into what we actually require. Hierarchical types are required to be able to query for a result set of mixed types.
+
+* Entity
+    * Domain Object
+        * Incidence
+            * Event
+            * Todo
+            * Journal
+            * Freebusy
+        * Note
+        * Mail
+        * Contact
+        * Collection
+            * Akonadi Resource
+            * Mail Folder
+            * Calendar
+            * Todolist
+            * Journal
+            * Address Book
+        * Relation
+            * Tag
+            * Contact Group
+            * Thread
+
+#### Properties
+```no-highlight
+Entity: The smallest unit in the akonadi universe
+    id: unique identifier in the akonadi storage. Not persistant over db recreations and can therefore only be referenced from within the akonadi database.
+    revision: revision of the entity
+    resource: reference to AkonadiResource:id
+```
+```no-highlight
+Domain Object:
+    uid: unique identifier of the domain object.
+```
+```no-highlight
+Event:
+    summary: A string containing a short summary of the event.
+    startDate: The start date of the event.
+    startTime: The start time of the event. Optional.
+```
+
+### References/Hierachies
+Some domain objects reference others, and that is often used to build hierarchies.
+Examples are folder hierachies, tags, todo hierarchies, mail threads, contact groups, etc.
+
+These references can be built on two levels:
+* On the akonadi entity level: The referenced object *must* be available in local storage, and we're only linking to that specific instance. If the referenced entity is removed, the reference breaks. The reference always only references a single akonadi entity.
+* On the domain object level: The reference can remain also if no object currently matches the reference. The reference automatically applies to new entities containing an object with the referenced uid. More than one entity can be matched if they contain the same domain object.
+
+#### Examples
+The following hierachies exist among others:
+
+* Parent Collection
+    * Given by the source (path of the folder in IMAP)
+    * Parent folder "owns" the sub entity
+    * Link exists on the akonadi entity level: We specify where the entity lives, this MUST always be a single parent entity.
+* Subtodos
+    * Given by the todo itself
+    * Not necessarly owning (though often implemented as such, similar to threading)
+    * Link exists on domain object level.
+* Mail Threads
+    * Non owning, but a mail always only belongs to one thread.
+    * Hierarchy given by message-id references in headers and subject + date.
+    * Link exists on domain object level.
+* Contact Groups
+    * A contact can belong to many groups and the reference is non-owning.
+    * Link exists on domain object level.
+* Tags
+    * An entity can have many tags
+    * The tag references the entity, not the other way around.
+    * Link exists on domain object level.
+
+#### Example queries:
+* All mail folders of a resource
+* All threads within date-time range
diff --git a/docs/clientapi.md b/docs/clientapi.md
index 59998ca..58fbb13 100644
--- a/docs/clientapi.md
+++ b/docs/clientapi.md
@@ -17,35 +17,11 @@ The client API consists of:
 A set of standardized domain types is defined. This is necessary to decouple applications from resources (so a calendar can access events from all resources), and to have a "language" for queries.
 
 The definition of the domain model directly affects:
-* granularity for data retrievel (email property, or individual subject, date, ...)
-* queriable properties (sender, id, ...)
-* properties used for sorting (10 latest email)
+* granularity for data retrieval (email property, or individual subject, date, ...)
+* queriable properties for filtering and sorting (sender, id, ...)
 
 The purpose of these domain types is strictly to be the interface and the types are not meant to be used by applications directly, or to be restricted by any other specifications (such as ical). By nature these types will be part of the evolving interface, and will need to be adjusted for every new property that an application must understand.
 
-### Application Domain Types
-This is a proposed set of types that we will need to evolve into what we actually require. Hierarchical types are required to be able to query for a result set of mixed types.
-
-* Entity
-    * Item
-        * Incidence
-            * Event
-            * Todo
-            * Journal
-            * Freebusy
-        * Note
-        * Mail
-        * Contact
-    * Collection
-        * Mail Folder
-        * Calendar
-        * Tasklist
-        * Journal
-        * Contact Group
-        * Address Book
-    * Relation
-        * Tag
-
 ## Store Facade
 The store is always accessed through a store specific facade, which hides:
 * store access (one store could use a database, and another one plain files)
@@ -72,7 +48,7 @@ The changeset can be recorded by the domain object adapter while the properties
 Each modification is associated with a specific revision, which allows the synchronizer to do automatic conflict resolution.
 
 ### Conflict Resolution
-Conflicts can occur at two points in the client:
+Conflicts can occur at two points:
 
 * While i.e. an editor is open and we receive an update for the same entity
 * After a modification is sent to the synchronizer but before it's processed
diff --git a/docs/design.md b/docs/design.md
index 59cdf74..fe0d214 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -1,4 +1,4 @@
-# Goals
+# Design Goals
 ## Axioms
 1. Personal information is stored in multiple sources (address books, email stores, calendar files, ...)
 2. These sources may local, remote or a mix of local and remote
@@ -39,27 +39,18 @@ Implications of the above:
 
 # Overview
 
-# Types
-## Domain Type
+## Types
+### Domain Type
 The domain types exposed in the public interface.
 
-## Buffer Type
+### Buffer Type
 The individual buffer types as specified by the resource. The are internal types that don't necessarily have a 1:1 mapping to the domain types, although that is the default case that the default implementations expect.
 
-## Steps to add support for new types
-* Add new type to applicationdomaintypes.h and implement `getTypenName()`
-* Implement `TypeImplementation<>` for updating indexes etc.
-* Add a type.fbs default schema for the type
-
-## Steps for adding support for a type to a resource
-* Add a TypeAdaptorFactory, which can either register resource specific mappers, or stick to what the default implementation in TypeImplementation provides
-* Add a TypeFacade that injects the TypeAdaptorFactory in the GenericFacade
-* Register the facade in the resource
-* Add synchronization code that creates the relevant objects
-
-# Change Replay
+### Change Replay
 The change replay is based on the revisions in the store. Clients (and also the write-back mechanism), are informed that a new revision is available. Each client can then go through all new revisions (starting from the last seen revision), and thus update it's state to the latest revision.
 
+# Client API
+
 # Tradeoffs/Design Decisions
 * Key-Value store instead of relational
     * `+` Schemaless, easier to evolve
diff --git a/docs/extendingakonadi.md b/docs/extendingakonadi.md
new file mode 100644
index 0000000..fe38e87
--- /dev/null
+++ b/docs/extendingakonadi.md
@@ -0,0 +1,11 @@
+## Steps to add support for new types
+* Add new type to applicationdomaintypes.h and implement `getTypenName()`
+* Implement `TypeImplementation<>` for updating indexes etc.
+* Add a type.fbs default schema for the type
+
+## Steps for adding support for a type to a resource
+* Add a TypeAdaptorFactory, which can either register resource specific mappers, or stick to what the default implementation in TypeImplementation provides
+* Add a TypeFacade that injects the TypeAdaptorFactory in the GenericFacade
+* Register the facade in the resource
+* Add synchronization code that creates the relevant objects
+
diff --git a/docs/storage.md b/docs/storage.md
index 3a8d74a..26469a7 100644
--- a/docs/storage.md
+++ b/docs/storage.md
@@ -163,7 +163,7 @@ Other useful properties:
     * No updates since September 2013
 * http://unqlite.org
     * bad performance with large database (looks like O(n))
-    * like lmdb roughly 2*datasize
+    * like lmdb roughly 2\*datasize
     * includes a document store
     * mmapped ready access
     * reading about 30% the speed of lmdb
@@ -181,9 +181,9 @@ Since indexes always need to be updated they directly affect how fast we can wri
     * fast fulltext searching
     * No MVCC concurrency
     * Only supports one writer at a time
-    * If a reader is reading blocks that have now been changed by a writer, it throws a DatabaseModifiedException. This means most of the Xapian code needs to be in wihle (1) { try { .. } catch () } blocks and needs to be able to start from scratch.
+    * If a reader is reading blocks that have now been changed by a writer, it throws a DatabaseModifiedException. This means most of the Xapian code needs to be in `while (1) { try { .. } catch () }` blocks and needs to be able to start from scratch.
     * Wildcard searching (as of 2015-01) isn't ideal. It works by expanding the word into all other words in the query and that typically makes the query size huge. This huge query is then sent to the database. Baloo has had to configure this expanding of terms so that it consumes less memory.
-    * Non existent UTF support - It does not support text normalization and splitting the terms at custom characters such as '_'.
+    * Non existent UTF support - It does not support text normalization and splitting the terms at custom characters such as '\_'.
 * lmdb:
     * sorted keys
     * sorted duplicate keys
@@ -200,9 +200,9 @@ Since indexes always need to be updated they directly affect how fast we can wri
 
 ## Useful Resources
 * LMDB
-    * Wikipedia for a good overview: https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database
-    * Benchmarks: http://symas.com/mdb/microbench/
-    * Tradeoffs: http://symas.com/is-lmdb-a-leveldb-killer/
-    * Disk space benchmark: http://symas.com/mdb/ondisk/
-    * LMDB instead of Kyoto Cabinet as redis backend: http://www.anchor.com.au/blog/2013/05/second-strike-with-lightning/
+    * Wikipedia for a good overview: <https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database>
+    * Benchmarks: <http://symas.com/mdb/microbench/>
+    * Tradeoffs: <http://symas.com/is-lmdb-a-leveldb-killer/>
+    * Disk space benchmark: <http://symas.com/mdb/ondisk/>
+    * LMDB instead of Kyoto Cabinet as redis backend: <http://www.anchor.com.au/blog/2013/05/second-strike-with-lightning/>