4 files changed, 65 insertions, 57 deletions

diff --git a/docs/clientapi.md b/docs/clientapi.md
index a2ac18e..59998ca 100644
--- a/docs/clientapi.md
+++ b/docs/clientapi.md
@@ -1,18 +1,17 @@
 The client API consists of:
 
-* a modification API for messages (Create/Modify/Delete)
-* a query API to retrieve messages
+* a modification API for entities (Create/Modify/Delete)
+* a query API to retrieve entities
 * a resource facade to abstract the resource implementation details
 * a set of standardized domain types
 * a notification mechanism to be notified about changes from individual stores
 
 ## Requirements/Design goals
 * zero-copy should be possible (mmap support)
-    * Likely only possible until application domain until we rewrite portions of the applications
+    * A single copy is more realistic
     * Most importantly we should hide how the data is stored (in parts, or one mmapped buffer)
-    * Support for mmapped buffers implies that we keep track of the lifetime of the loaded values.
-* property-level on-demand loading
-* streaming support for certain properties (attachments)
+* property-level on-demand loading of data
+* streaming support for large properties (attachments)
 
 ## 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.
@@ -24,42 +23,35 @@ The definition of the domain model directly affects:
 
 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.
 
-### Akonadi Domain Types
+### 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.
 
-Items:
-
-* Item
-    * incidence
-        * Event
-        * Todo
+* Entity
+    * Item
+        * Incidence
+            * Event
+            * Todo
+            * Journal
+            * Freebusy
+        * Note
+        * Mail
+        * Contact
+    * Collection
+        * Mail Folder
+        * Calendar
+        * Tasklist
         * Journal
-        * Freebusy
-    * Note
-    * Mail
-    * Contact
-
-Collections:
-
-* Collection
-    * Mail Folder
-    * Calendar
-    * Tasklist
-    * Journal
-    * Contact Group
-    * Address Book
-
-Relations:
-
-* Relation
-    * Tag
+        * 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)
 * message type (flatbuffers, ...)
 * indexes
-* syncronizer communication
+* synchronizer communication
 * notifications
 
 This abstraction layer allows each resource to separately define how data is stored and retrieved. Therefore tradeoffs can be defined to suit the expected access patters or structure of source data. Further it allows individual resources to choose different technologies as suitable. Logic can still be shared among resources, while keeping the maintenance effort reasonable, by providing default implementations that are suitable for most workloads.
@@ -67,7 +59,7 @@ This abstraction layer allows each resource to separately define how data is sto
 Because the facade also implements querying of indexes, a resource my use server-side searching to fullfill the query, and fallback to local searches when the server is not available.
 
 ## Modifications
-Modifications are stored by the client sending modification commands to the syncronizer. The syncronizer is responsible for ensuring that modification are not lost and eventually persistet. A small window exists therefore where a modification is transferred to the syncronizer where a modifications can get lost.
+Modifications are stored by the client sending modification commands to the synchronizer. The synchronizer is responsible for ensuring that modification are not lost and eventually persistet. A small window exists therefore where a modification is transferred to the synchronizer where a modifications can get lost.
 
 The API consists of the following calls:
 
@@ -75,23 +67,23 @@ The API consists of the following calls:
 * modify(domainObject, resource)
 * remove(domainObject, resource)
 
-The changeset can be recorded by the domain object adapter while the properties are set, and are then sent to the syncronizer once modify is called.
+The changeset can be recorded by the domain object adapter while the properties are set, and are then sent to the synchronizer once modify is called.
 
-Each modification is associated with a specific revision, which allows the syncronizer to do automatic conflict resolution.
+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:
 
 * While i.e. an editor is open and we receive an update for the same entity
-* After a modification is sent to the syncronizer but before it's processed
+* After a modification is sent to the synchronizer but before it's processed
 
-In the first case the client is repsonsible to resolve the conflict, in the latter case it's the syncronizer's responsibility.
-A small window exists where the client has already started the modification (i.e. command is in socket), and a notification has not yet arrived that the same entity has been changed. In such a case the syncronizer may reject the modification because it has the revision the modification refers to no longer available.
+In the first case the client is repsonsible to resolve the conflict, in the latter case it's the synchronizer's responsibility.
+A small window exists where the client has already started the modification (i.e. command is in socket), and a notification has not yet arrived that the same entity has been changed. In such a case the synchronizer may reject the modification because it has the revision the modification refers to no longer available.
 
-This design allows the syncronizer to be in control of the revisions, and keeps it from having to wait for all clients to update until it can drop revisions.
+This design allows the synchronizer to be in control of the revisions, and keeps it from having to wait for all clients to update until it can drop revisions.
 
 ## Query System
-The query system should allow for efficient retrieval for just the amount of data required by the client. Efficient querying will be supported by the indexes povided by the resources.
+The query system should allow for efficient retrieval for just the amount of data required by the client. Efficient querying will be supported by the indexes provided by the resources.
 
 The query always retrieves a set of entities matching the query, while not necessarily all properties of the entity need to be populated.
 
@@ -187,12 +179,12 @@ Generic:
 ### Lazy Loading ###
 The system provides property-level lazy loading. This allows i.e. to defer downloading of attachments until the attachments is accessed, at the expense of having to have access to the source (which could be connected via internet).
 
-To achieve this, the query system must check for the availability of all requested properties on all matched entities. If a property is not available the a command should be sent to the synchronizer to retrieve said properties. Once all properties are available the query can complete.
+To achieve this, the query system must check for the availability of all requested properties on all matched entities. If a property is not available, a command must be sent to the synchronizer to retrieve said properties. Once all properties are available the query can complete.
 
 Note: We should perhaps define a minimum set of properties that *must* be available. Otherwise local search will not work. On the other hand, if a resource implements server-side search, it may not care if local search doesn't work.
 
 ### Data streaming ###
-Large objects such as attachments should be streamable. An API that allows to retrieve a single property of a defined entity in a streamable fashion is probably enough.
+Large properties such as attachments should be streamable. An API that allows to retrieve a single property of a defined entity in a streamable fashion is probably enough.
 
 ### Indexes ###
 Since only properties of the domain types can be queried, default implementations for commonly used indexes can be provided. These indexes are populated by generic preprocessors that use the domain-type interface to extract properties from individual entites.
@@ -200,14 +192,5 @@ Since only properties of the domain types can be queried, default implementation
 ## Notifications ##
 A notification mechanism is required to inform clients about changes. Running queries will automatically update the result-set if a notification is received.
 
-A notification constist of:
-
-* The latest revision of the store
-* A hint what properties changed
-
-The revision allows the client to only fetch the data that changed.
-The hint allows the client to avoid fetching that it's not interested in.
-A running query can do all of that transparently behind the scenes.
-
-Note that the hints should indeed only hint what has changed, and not supply the actual changeset. These hints should be tailored to what we see as useful, and must therefore be easy to modify.
-
+Note: A notification could supply a hint on what changed, allowing clients to ignore revisions with irrelevant changes. 
+A running query can do all of that transparently behind the scenes. Note that the hints should indeed only hint what has changed, and not supply the actual changeset. These hints should be tailored to what we see as useful, and must therefore be easy to modify.
diff --git a/docs/design.md b/docs/design.md
index 9b074b1..59cdf74 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -89,7 +89,7 @@ The change replay is based on the revisions in the store. Clients (and also the
 * Shared domain types as common interface for client applications
     * `-` yet another abstraction layer that requires translation to other layers and maintenance
     * `+` decoupling of domain logic from data access
-    * `+` allows to evolve types according to needs (not coupled to specific applicatoins domain types)
+    * `+` allows to evolve types according to needs (not coupled to specific application domain types)
 
 # Risks
 * key-value store does not perform with large amounts of data
diff --git a/docs/resource.md b/docs/resource.md
index 847831d..bba4dbb 100644
--- a/docs/resource.md
+++ b/docs/resource.md
@@ -4,9 +4,9 @@ The resource consists of:
 * a plugin providing the client-api facade
 * a configuration setting up the filters
 
-# Syncronizer
+# Synchronizer
 * The synchronization can either:
-    * Generate a full diff directly on top of the db. The diffing process can work against a single revision, and could even stop writing other changes to disk while the process is ongoing (but doesn't have to due to the revision). It then generates a necessary changeset for the store.
+    * Generate a full diff directly on top of the db. The diffing process can work against a single revision/snapshot (using transactions). It then generates a necessary changeset for the store.
     * If the source supports incremental changes the changeset can directly be generated from that information.
 
 The changeset is then simply inserted in the regular modification queue and processed like all other modifications.
diff --git a/docs/terminology.md b/docs/terminology.md
new file mode 100644
index 0000000..4b49f2d
--- /dev/null
+++ b/docs/terminology.md
@@ -0,0 +1,25 @@
+Consistent, agreed-upon terminology is key to being able to work together efficiently on a complex software project such as this, particularly as we are building on the earlier Akonadi efforts which itself has established terminology. You can find the current glossary here.
+
+It is recommended to familiarize yourself with the terms before going further into the design of Akonadi-next as it will make things clearer for you and easier to ask the questions you have in a way that others will understand immediately.
+
+## Glossary of Akonadi-Next Terms
+* akonadi1: The current akonadi implementation that uses a central server and an SQL database
+* akonadi-next: This is the codename for the project. In the long run this is supposed to be folded into regular akonadi, so we will never release a product called akonadi-next.
+* client: any application which accesses data using akonadi
+* entity: The atomic unit for a given type of data. An email is an entity; an email folder is an entity; a calendar event is an entity; a contact is an entity; etc. Different kinds of entities may have their own data structure, but conceptually they are equivalent in most other ways.
+* revision: A version of the store. One entity may have multiple revisions in a store, representing (for instance) the local state and the synchronized state of the entity.
+* source: The canonical data set, which may be a remote IMAP server, a local iCal file, a local maildir, etc.
+* store: The local, persistent (e.g. on disk) record of entities belonging to a source. This may be a full mirror of the data or simply metadata, a detail left up to the resource. The format of the data in the store is defined by the resource that owns it.
+* resource: A plugin which provides client command processing, a store facade and synchronization for a given type of store. The resource also manages the configuration for a given source including server settings, local paths, etc.
+* store facade: An object provided by resources which provides transformations between domain objects and the store.
+* synchronizer: The operating system process responsible for overseeing the process of modifying and synchronizing a store. To accomplish this, a synchronizer loads the correct resource plugin, manages pipelines and handles client communication. One synchronizer is created for each source that is accessed by clients; these processes are shared by all clients.
+* Preprocessor: A component that takes an entity and performs some modification of it (e.g. changes the folder an email is in) or processes it in some way (e.g. indexes it)
+* pipeline: A run-time definable set of filters which are applied to an entity after a resource has performed a specific kind of function on it (add, update, remove)
+* query: A declarative method for requesting entities from one or more sources that match a given set of constraints
+* command: Clients request modifications, additions and deletions to the store by sending commands to a synchronizer for processing
+* command queue: A queue of commands kept by the synchronizer to ensure durability and, when necessary, replayability
+* notification: A message sent from a synchronizer to inform the client of a change in the store
+* domain object: An application domain object, i.e. an event.
+* domain type: The type of a domain object. i.e. Akonadi2::ApplicationDomain::Event
+* buffer: The buffers used by the resources to persist data in the datastore.
+* buffer type: The individual buffer types as specified by the resource. These 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.