service/crm.md

@@ -293,20 +293,40 @@ target difficult to fulfill at this point.
 <!-- "architectural" document, which the final result might differ -->
 <!-- from, sometimes significantly -->
 
+CiviCRM is a relatively "classic" PHP application: it's made of a
+collection of `.php` files scattered cleverly around various
+directories. There's one catch: it's actually built as a drop-in
+module for other CMSes. Traditionnally, Joomla, Wordpress and Drupal
+are supported, and our deployment uses Drupal.
+
+(There's actually a standalone version in development we are
+interested in as well, as we do not need the features from the Drupal
+site.)
+
+Most code lives in a `torcrm` module that processes Redis messages
+through CiviCRM jobs.
+
+CiviCRM is isolated from the public internet through [HTTP
+authentication](#authentication). Communication with the [donation frontend](service/donate)
+happens through a [Redis queue](#queues). See also the [donation site
+architecture for more
+background](service/donate#design-and-architecture).
+
 ## Services
 
-The CiviCRM service runs on the `crm-int-01` server:
-
-   * software:
-     * CiviCRM on top of Drupal
-     * Drupal has a `tor_donation` module which has the code to
-       receive/process Redis messages and initiate the corresponding
-       actions in CiviCRM
-     * Apache with PHP FPM
-     * MariaDB (MySQL) database (Drupal storage backend)
-     * Redis cache (?)
-     * Dovecot IMAP server (to handle bounces)
-   * sites:
+The CiviCRM service runs on the `crm-int-01` server, with the
+following layer:
+
+- Apache: TLS decapsulation, HTTP authentication and reverse proxy
+- PHP FPM: PHP runtime which Apache connects to over FastCGI
+- Drupal: PHP entry point, loads CiviCRM code as a module
+- CiviCRM: core of the business logic
+- MariaDB (MySQL) database (Drupal and CiviCRM storage backend)
+- Redis server: communication between CiviCRM and the donate frontend
+- Dovecot: IMAP server to handle bounces
+
+Apache answers to the following virtual hosts:
+
  * `crm.torproject.org`: production CiviCRM site
  * `staging.crm.torproject.org`: staging site
  * `test.crm.torproject.org`: testing site
@@ -336,12 +356,20 @@ See also the [kill switch enabled](#kill-switch-enabled) playbook.
 
 ## Interfaces
 
-<!-- TODO: e.g. web APIs, commandline clients, etc -->
+Most operations with CiviCRM happen over a web interface, in a web
+browser. There is a [CiviCRM API](https://docs.civicrm.org/dev/en/latest/api/) but it's rarely used by Tor's
+operators.
+
+The `torcivicrm` user has a command-line CiviCRM tool called [`cv`](https://github.com/civicrm/cv)
+in its `$PATH` which talks to that API to perform various functions.
+
+Drupal also has its own shell tool called [drush](https://www.drush.org/).
 
 ## Authentication
 
 The `crm-int-01` server doesn't talk to the outside internet and can
-be accessed only via HTTP authentication.
+be accessed only via HTTP Digest authentication. We are considering
+[changing this to basic auth](https://gitlab.torproject.org/tpo/web/civicrm/-/issues/147).
 
 Users that need to access the CRM must be added to the Apache `htdigest` file
 on `crm-int-01.tpo` and have a CiviCRM account created from them.
@@ -488,7 +516,11 @@ Only the last metric above is hooked up to alerting for now, see
 
 ## Tests
 
-TODO: what to test on major CiviCRM upgrades?
+TODO: what to test on major CiviCRM upgrades, specifically in CiviCRM?
+
+There's a [test procedure in donate.torproject.org](service/donate#tests) that should
+likely be followed when there are significant changes performed on
+CiviCRM.
 
 ## Logs
 
@@ -504,13 +536,6 @@ Resque Processing" job, then view the logs. There may also be fatal
 errors logged in the general CiviCRM log, under Administer > Admin
 Console > View Log.
 
-### Middleware logs
-
-The PHP middleware responsible for bridging the Redis queue with CiviCRM logs
-to syslog on `crm-int-01`. Those logs can be read using `journalctl -t
-processor`. They can be useful to determine the cause of donations being
-submitted but not showing up in CiviCRM.
-
 ## Backups
 
 Backups are done with the regular [backup procedures](service/backup) except for