[docs] revamp bitmask dev docs

1 files changed, 88 insertions, 0 deletions

diff --git a/docs/mail/index.rst b/docs/mail/index.rst
new file mode 100644
index 00000000..22bdcf4d
--- /dev/null
+++ b/docs/mail/index.rst
@@ -0,0 +1,88 @@
+:LastChangedDate: $LastChangedDate$
+:LastChangedRevision: $LastChangedRevision$
+:LastChangedBy: $LastChangedBy$
+
+.. _mail:
+
+Bitmask Mail
+================================
+*decentralized and secure mail delivery and synchronization*
+
+This is the documentation for the ``leap.mail`` module. It is a `twisted`_
+module, hanging from the ``leap.bitmask`` namespace, that allows to receive, process, send and access existing messages using the `LEAP`_ platform.
+
+One way to use this library is to let it launch two standard mail services,
+``smtp`` and ``imap``, that run as local proxies and interact with a remote
+``LEAP`` provider that offers *a soledad syncronization endpoint* and receives 
+the outgoing email. This is what `Bitmask`_ client does.
+
+From the mail release 0.4.0 on, it's also possible to use a protocol-agnostic email
+public API, so that third party mail clients can manipulate the data layer. This
+is what the awesome MUA in the `Pixelated`_ project is using.
+
+From release 0.10 on, the Bitmask Bundles will also ship a branded version of
+the Pixelated User Agent, that will be served locally. This will be one of the
+recommended ways of accessing the user emails. The other will be Thunderbird, by
+using the `Bitmask Thunderbird Extension`_.
+
+Note that this used to be a standalone python package, under the ``leap.mail``
+namespace. It was merged into bitmask repo, so it now lives in the
+``leap.bitmask.mail`` namespace. The `legacy repo`_ will no longer be updated.
+
+.. _`twisted`: https://twistedmatrix.com/trac/
+.. _`LEAP`: https://leap.se/en/docs
+.. _`Bitmask`: https://bitmask.net/en/features#email
+.. _`Pixelated`: https://pixelated-project.org/
+.. _`legacy repo`: https://github.com/leapcode/leap_mail/
+.. _`Bitmask Thunderbird Extension`: https://addons.mozilla.org/en-US/thunderbird/addon/bitmask/
+
+How does Bitmask Mail work?
+----------------------------
+
+All the underlying data storage and sync is handled by a library called
+`soledad`_, which handles encryption, storage and sync. Based on `u1db`_,
+documents are stored locally as local ``sqlcipher`` tables, and syncs against
+the soledad sync service in the provider.
+
+OpenPGP key generation and keyring management are handled by another leap
+python library: `keymanager`_.
+
+See :ref:`the life cycle of a leap email <mail_journey>` for an overview of the life cycle
+of an email through ``LEAP`` providers.
+
+.. _`Soledad`: https://leap.se/en/docs/design/soledad
+.. _`u1db`: https://en.wikipedia.org/wiki/U1DB
+.. _`keymanager`: https://github.com/leapcode/keymanager/
+
+The life cycle of a LEAP Email
+------------------------------
+
+For a better picture, you are invited to read about :ref:`the whole journey of a mail in the LEAP system <journey>`.
+
+
+Data model
+--------------------
+
+.. TODO clear document types documentation.
+
+The data model at the present moment consists of several *document types* that split email into different documents that are stored in ``Soledad``. The idea behind this is to
+keep clear the separation between *mutable* and *inmutable* parts, and still being able to
+reconstruct arbitrarily nested email structures easily.
+
+Authentication
+---------------------
+Currently, IMAP and SMTP are twisted services that are binded to ``localhost``. These services be initialized by the bitmask.core daemon, but they are not tied to any user session. When an use attempts to log in to those services, a ``twisted.cred`` pluggable authentication plugin will try to lookup a ``mail token`` that is stored inside the soledad encrypted storage.
+
+
+
+
+Mail development resources
+--------------------------
+
+Some old notes that might help you while developing or debugging bitmask mail
+issues.
+
+.. toctree::
+
+   hacking
+