service/lists.md

@@ -211,11 +211,20 @@ accessible for modification.
 <!-- if you do not find what you are looking for here, it is a bug -->
 <!-- please file it -->
 
-## TODO Disaster recovery
+## Disaster recovery
 
-<!-- what to do if all goes to hell. e.g. restore from backups? -->
-<!-- rebuild from scratch? not necessarily those procedures (e.g. see -->
-<!-- "Installation" below but some pointers. -->
+### Data loss
+
+If a server is destroyed or its data partly destroyed, it should be
+able to recover on-disk files through the normal [backup](howto/backup) system,
+with a RTO of about 24h.
+
+Puppet should be able to rebuild a mostly functional Mailman 3 base
+install, although it might trip upon the PostgreSQL configuration. If
+that's the case, first try by flipping PostgreSQL off in the Puppet
+configuration, bootstrap, then run it again with the flip on.
+
+<!-- TODO: Confidentiality breaches -->
 
 # Reference
 
@@ -329,18 +338,25 @@ we're relying on Debian packages for this.
 
 There's no SLA specifically associated with this service.
 
-## TODO Design and architecture
+## Design and architecture
+
+Mailman 3 has a relatively more complex architecture than
+Mailman 2. The [upstream architecture page](https://docs.mailman3.org/en/latest/architecture.html) does a good job at
+explaining it, but essentially there is:
 
-<!-- how this is built -->
-<!-- should reuse and expand on the "proposed solution" discussed in -->
-<!-- a previous RFC or the Discussion section below. it's a -->
-<!-- "as-built" documented, whereas the "Proposed solution" is an -->
-<!-- "architectural" document, which the final result might differ -->
-<!-- from, sometimes significantly -->
+- a REST API server ("mailman-core")
+- a Django web frontend ("Postorius")
+- a archiver ("Hyperkitty", meow)
+- a mail and web server
 
-TODO: explain a bit the mailman3 architecture, see https://docs.mailman3.org/en/latest/architecture.html
+![diagram of mailman's architecture](https://docs.mailman3.org/en/latest/_images/mailman-architecture.png)
 
-TODO mention zope and django in the same sentence
+In our email architecture, the mailing list server (`lists-01`) only
+handles mailman lists. It receives mail on `lists.torproject.org`,
+stores it in archives (or not), logs things, normally rewrites the
+email and broadcasts it to a list of email addresses, which Postfix
+(on `lists-01`) routes to the wider internet, including other
+`torproject.org` machines.
 
 ## Services