# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1446239870 -3600
# Node ID d683d5ebaf8d2f677df9d0fcfa9f5b9ddbccb571
# Parent  cec34b884f4066878c73ef7835f2679d3443ce0d
Added diagrams and improved local SMTP routing details.

diff -r cec34b884f40 -r d683d5ebaf8d docs/wiki/FrontPage
--- a/docs/wiki/FrontPage	Fri Oct 30 21:26:11 2015 +0100
+++ b/docs/wiki/FrontPage	Fri Oct 30 22:17:50 2015 +0100
@@ -26,6 +26,39 @@
  giving you the freedom to see what the software does, as well as the freedom
  to modify and share the software with others.
 
+{{{#!graphviz
+//format=svg
+//transform=notugly
+digraph architecture {
+  node [shape=box,fontsize="16.0",fontname="sans-serif",tooltip="The imip-agent architecture"];
+  edge [tooltip="The imip-agent architecture"];
+  rankdir=LR;
+
+  mail [label="Incoming mail",shape=folder,style=filled,fillcolor=cyan];
+  MTA [label="MTA\n(Exim, Postfix, ...)",tooltip="MTA"];
+
+  subgraph {
+    rank=same;
+    agent [label="imip-agent",style=filled,fillcolor=gold];
+    scheduling [label="Scheduling",shape=ellipse,style=filled,fillcolor=gold];
+    freebusy [label="Free/busy",shape=folder,style=filled,fillcolor=gold];
+    manager [label="imip-manager",style=filled,fillcolor=gold];
+  }
+
+  mailbox [label="Mailboxes\n(Cyrus, Dovecot, ...)",tooltip="Mailboxes"];
+  webserver [label="Web server\n(Apache, ...)",tooltip="Web server"];
+  client [label="Mail clients"];
+  browser [label="Web browsers"];
+
+  mail -> MTA -> agent -> mailbox -> client;
+  agent -> scheduling -> freebusy -> webserver -> client;
+  freebusy -> manager;
+  manager -> webserver [penwidth="3.0"];
+  webserver -> browser [penwidth="3.0"];
+  scheduling -> MTA -> mail [style=dashed];
+}
+}}}
+
 Unlike some monolithic groupware solutions...
 
  * It does not require you to change your [[/MailIntegration|mail delivery]]
diff -r cec34b884f40 -r d683d5ebaf8d docs/wiki/MailIntegration
--- a/docs/wiki/MailIntegration	Fri Oct 30 21:26:11 2015 +0100
+++ b/docs/wiki/MailIntegration	Fri Oct 30 22:17:50 2015 +0100
@@ -12,6 +12,45 @@
 Otherwise, few constraints should be imposed by each kind of system on the
 other.
 
+{{{#!graphviz
+//format=svg
+//transform=notugly
+digraph mail_integration {
+  node [shape=box,fontsize="16.0",fontname="sans-serif",tooltip="Mail integration"];
+  edge [tooltip="Mail integration"];
+  rankdir=LR;
+
+  mail [label="Incoming mail",shape=folder,style=filled,fillcolor=cyan];
+
+  subgraph {
+    rank=same;
+    personrouter [label="Person router"];
+    resourcerouter [label="Resource router"];
+    recipients [label="Recipient database",shape=folder];
+  }
+
+  subgraph {
+    rank=same;
+    personhandler [label="Person handler",style=filled,fillcolor=gold];
+    resourcehandler [label="Resource handler",style=filled,fillcolor=gold];
+    scheduling [label="Scheduling",shape=ellipse,style=filled,fillcolor=gold];
+    freebusy [label="Free/busy",shape=folder,style=filled,fillcolor=gold];
+  }
+
+  mailbox [label="Mailboxes\n(Cyrus, Dovecot, ...)",tooltip="Mailboxes"];
+
+  mail -> personrouter -> personhandler -> mailbox;
+  mail -> resourcerouter -> resourcehandler
+
+  recipients -> personrouter;
+  recipients -> resourcerouter;
+
+  personhandler -> scheduling;
+  resourcehandler -> scheduling;
+  scheduling -> freebusy;
+}
+}}}
+
 == MTAs ==
 
 Currently, imip-agent supports [[http://exim.org/|Exim]] and
@@ -88,3 +127,6 @@
 ==
 [[/LMTP|LMTP]]            || Exim, Postfix
 }}}
+
+See the [[../MailboxIntegration|mailbox integration guide]] for a brief
+overview of configuring mail storage solutions.
diff -r cec34b884f40 -r d683d5ebaf8d docs/wiki/MailIntegration--LDAP
--- a/docs/wiki/MailIntegration--LDAP	Fri Oct 30 21:26:11 2015 +0100
+++ b/docs/wiki/MailIntegration--LDAP	Fri Oct 30 22:17:50 2015 +0100
@@ -27,9 +27,17 @@
 `020_exim4-config_ldap_resources`
 ==
 `020_exim4-config_ldap_people_outgoing_recipients`
+}}}
+
+Where [[../LocalSMTP|local SMTP routing]] is being performed, the following
+file is also useful:
+
+{{{#!table
+'''File''' || '''Purpose'''
 ==
 `020_exim4-config_ldap_people_local`
-|| Defines routing for local recipients for delivery to local mailboxes
+|| Defines routing for local recipients for delivery to local system
+.. mailboxes
 }}}
 
 These files can be incorporated into the Exim configuration. On Debian
@@ -57,6 +65,9 @@
 systems, `main.cf.example` can be merged into `/etc/postfix/main.cf`,
 whereas the remaining files would be installed into `/etc/postfix/ldap`.
 
+Where [[../LocalSMTP|local SMTP routing]] is being performed, the local
+recipient entry in the `conf/postfix/transport` file is used.
+
 == LDAP Representations for Mail Recipients ==
 
 Relevant LDAP resources for structuring recipient information include the
diff -r cec34b884f40 -r d683d5ebaf8d docs/wiki/MailIntegration--LocalSMTP
--- a/docs/wiki/MailIntegration--LocalSMTP	Fri Oct 30 21:26:11 2015 +0100
+++ b/docs/wiki/MailIntegration--LocalSMTP	Fri Oct 30 22:17:50 2015 +0100
@@ -18,7 +18,45 @@
 
 The local delivery mechanism would then deposit the message in the user's mailbox.
 
-Where the mail system must instead route messages to mailbox providers
-employing LMTP, some more effort is required. For Exim, some sample
-configuration files are provided in `conf/exim/lmtp` to route messages for local
-users to LMTP endpoints.
+{{{#!graphviz
+//format=svg
+//transform=notugly
+digraph local_smtp {
+  node [shape=box,fontsize="16.0",fontname="sans-serif",tooltip="Local SMTP delivery"];
+  edge [tooltip="Local SMTP delivery"];
+  rankdir=LR;
+
+  mail [label="Incoming mail",shape=folder,style=filled,fillcolor=cyan];
+
+  subgraph {
+    rank=same;
+    personrouter [label="Person router"];
+    localrouter [label="Local router"];
+    recipients [label="Recipient database",shape=folder];
+  }
+
+  subgraph {
+    rank=same;
+    personhandler [label="Person handler",style=filled,fillcolor=gold];
+    localtransport [label="Local transport"];
+  }
+
+  mailbox [label="Mailboxes\n(Cyrus, Dovecot, ...)",tooltip="Mailboxes"];
+
+  mail -> personrouter -> personhandler;
+
+  recipients -> personrouter;
+  recipients -> localrouter;
+
+  personhandler -> localrouter -> localtransport -> mailbox;
+}
+}}}
+
+MTAs typically provide delivery routing for local user mailboxes. Where the
+mail system must instead route messages to mailbox providers employing LMTP,
+some more effort may be required. See the
+[[../../MailboxIntegration|mailbox integration guide]] for more details.
+
+Configuration files for routing messages for explicitly-indicated local users
+are provided in the [[../../MailIntegration/LDAP|LDAP]] and
+[[../../MailIntegration/Simple|simple]] integration guides.
diff -r cec34b884f40 -r d683d5ebaf8d docs/wiki/MailIntegration--Simple
--- a/docs/wiki/MailIntegration--Simple	Fri Oct 30 21:26:11 2015 +0100
+++ b/docs/wiki/MailIntegration--Simple	Fri Oct 30 22:17:50 2015 +0100
@@ -24,9 +24,6 @@
 ==
 `020_exim4-config_people_outgoing_recipients`
 ==
-`020_exim4-config_people_local`
-|| Defines routing for local recipients for delivery to local mailboxes
-==
 `virtual_people`
 ||<rowspan="3"> Defines recipient identities belonging to known domains
 ==
@@ -36,6 +33,16 @@
 ==
 `virtual_domains`
 || Defines recipient domains
+}}}
+
+Where [[../LocalSMTP|local SMTP routing]] is being performed, the following
+files are also useful:
+
+{{{#!table
+'''File''' || '''Purpose'''
+==
+`020_exim4-config_people_local`
+|| Defines routing for local recipients for delivery to local mailboxes
 ==
 `virtual_people_local`
 || Defines recipients and local users for delivery to local mailboxes
@@ -43,7 +50,7 @@
 
 These files can be incorporated into the Exim configuration. On Debian
 systems, the numbered files can be copied into `/etc/exim4/conf.d/router`,
-whereas the virtual files can be copied into `/etc/exim4`.
+whereas the `virtual` files can be copied into `/etc/exim4`.
 
 == Using Lists with Postfix ==
 
@@ -59,6 +66,13 @@
 ||<rowspan="2"> Defines recipients and outgoing mail routing
 ==
 `virtual_alias_maps_people_outgoing`
+}}}
+
+Where [[../LocalSMTP|local SMTP routing]] is being performed, the following
+file is also useful:
+
+{{{#!table
+'''File''' || '''Purpose'''
 ==
 `virtual_alias_maps_local`
 || Defines recipients and local users for delivery to local mailboxes
diff -r cec34b884f40 -r d683d5ebaf8d docs/wiki/MailboxIntegration
--- a/docs/wiki/MailboxIntegration	Fri Oct 30 21:26:11 2015 +0100
+++ b/docs/wiki/MailboxIntegration	Fri Oct 30 22:17:50 2015 +0100
@@ -1,4 +1,3 @@
-= Mailbox Integration =
 = Mailbox Integration =
 
 Use of the imip-agent software should not affect the solutions chosen to store
@@ -10,16 +9,23 @@
 and mail storage is done, in case you have not already decided on a particular
 solution. Tested solutions are as follows:
 
- * [[http://www.cyrusimap.org/|Cyrus]] is a mail storage system that exposes
- mailboxes using the [[http://tools.ietf.org/html/rfc3501|IMAP]] protocol
-
- * [[http://dovecot.org/|Dovecot]] is a mail server that supports IMAP and
- [[http://tools.ietf.org/html/rfc1939|POP3]]. It can be configured to serve
- mail stored in traditional mailbox formats
-
+{{{#!table
+'''Solution''' || '''Details'''
+==
+[[http://www.cyrusimap.org/|Cyrus]] is a mail storage system that exposes
+mailboxes using the [[http://tools.ietf.org/html/rfc3501|IMAP]] protocol
+||
+The Cyrus documentation provides a guide on integrating Cyrus with
+[[http://www.cyrusimap.org/docs/cyrus-imapd/2.5.6/install-configure.php#mta|MTAs]].
+==
+[[http://dovecot.org/|Dovecot]] is a mail server that supports IMAP and
+[[http://tools.ietf.org/html/rfc1939|POP3]]. It can be configured to serve
+mail stored in traditional mailbox formats
+||
 The Dovecot documentation provides guides for integrating Dovecot with
 [[http://wiki2.dovecot.org/LMTP/Exim|Exim]] and with
 [[http://wiki2.dovecot.org/HowTo/PostfixDovecotLMTP|Postfix]].
+}}}
 
 == Exim ==
 
diff -r cec34b884f40 -r d683d5ebaf8d docs/wiki/OutgoingMessages
--- a/docs/wiki/OutgoingMessages	Fri Oct 30 21:26:11 2015 +0100
+++ b/docs/wiki/OutgoingMessages	Fri Oct 30 22:17:50 2015 +0100
@@ -12,6 +12,55 @@
 same effect as the outgoing message rule, as well as to notify any mail
 clients that would normally be managing calendar events on behalf of the user.
 
+{{{#!graphviz
+//format=svg
+//transform=notugly
+digraph outgoing {
+  node [shape=box,fontsize="16.0",fontname="sans-serif",tooltip="Outgoing messages"];
+  edge [tooltip="Outgoing messages"];
+  rankdir=LR;
+
+  mail [label="Outgoing mail",shape=folder,style=filled,fillcolor=cyan];
+
+  subgraph {
+    rank=same;
+    outgoingrouter [label="Outgoing router"];
+    personrouter [label="Person router"];
+  }
+
+  subgraph {
+    rank=same;
+    outgoinghandler [label="Outgoing handler",style=filled,fillcolor=gold];
+    personhandler [label="Person handler",style=filled,fillcolor=gold];
+    scheduling [label="Scheduling",shape=ellipse,style=filled,fillcolor=gold];
+    freebusy [label="Free/busy",shape=folder,style=filled,fillcolor=gold];
+    manager [label="imip-manager",style=filled,fillcolor=gold];
+  }
+
+  webserver [label="Web server\n(Apache, ...)",tooltip="Web server"];
+
+  subgraph {
+    rank=same;
+    client [label="Mail clients"];
+    browser [label="Web browsers"];
+  }
+
+  client -> mail;
+  mail -> outgoingrouter -> outgoinghandler;
+
+  browser -> webserver [penwidth="3.0"];
+  webserver -> manager [penwidth="3.0"];
+  manager -> mail [penwidth="3.0"];
+  mail -> personrouter [penwidth="3.0"];
+  personrouter -> personhandler [penwidth="3.0"];
+
+  outgoinghandler -> scheduling;
+  personhandler -> scheduling [penwidth="3.0"];
+  scheduling -> freebusy;
+  freebusy -> manager;
+}
+}}}
+
 == Events ==
 
 {{{#!table