service/donate.md

@@ -255,6 +255,29 @@ There is a staging server and development "review apps"
 (`donate-review-01`) that is managed by a `gitlab-runner` and driven
 by GitLab CI.
 
+The Django app is designed to be simple: all it's really doing is
+making an API request to CiviCRM, doing some templating, validating a
+form, and using the paypal/stripe API.
+
+Here is a sequence diagram built by @kez in January 2023
+([tpo/web/donate-static#107](https://gitlab.torproject.org/tpo/web/donate-static/-/issues/107#note_2872652)):
+
+```mermaid
+sequenceDiagram
+    user->>donate.tpo: visits the donation site
+    donate.tpo->>civicrm: requests the current perks, and prices
+    civicrm->>donate.tpo: stickers: 25, t-shirt: 75...
+    donate.tpo->>user: responds with a fully-rendered donation form
+    user->>donate.tpo: submits the donation form with stripe/paypal details
+    donate.tpo->>donate.tpo: validates form, creates payment contract with stripe/paypal
+    donate.tpo->>civicrm: submits donation and perk info
+    donate.tpo->>user: redirects to donation thank you page
+```
+
+As of this writing (August 2024), it's unclear whether the actual
+design follows this, see [tpo/web/donate-neo#79](https://gitlab.torproject.org/tpo/web/donate-neo/-/issues/79) for the task of
+clarifying those docs.
+
 ### Review apps
 
 Those are made of three parts:
@@ -435,6 +458,57 @@ static sites fronted by Apache. But because donate-neo is a Django
 application, it needs a specially-created deploy target for review
 apps.
 
+No formal proposal (i.e. TPA-RFC) was established to build this
+service, but a [discussion happened for the first prototype](https://gitlab.torproject.org/tpo/web/donate-static/-/issues/107).
+
+Here is the pitch @kez wrote to explain the motivation behind
+rebuilding the site in Django:
+
+> donate.tpo is currently implemented as a static lektor site that
+> communicates with a "middleware" backend (tpo/web/donate) via
+> javascript. this is counter-intuitive; why are the frontend and
+> backend kept so seperate? if we coupled the frontend and the backend a
+> bit more closely, we could drop most of the javascript (including the
+> javascript needed for payment processing), and we could create a
+> system that doesn't need code changes every time we want to update
+> donation perks
+>
+> with the current approach, the static mirror system serves static
+> html pages built by lektor. these static pages use javascript to
+> make requests to donate-api.tpo, our "middleware" server written in
+> php. the middleware piece then communicates with our civicrm
+> instance; this middleware -> civicrm communication is fragile, and
+> sometimes silently breaks
+>
+> now consider a flask or django web application. a user visits
+> donate.tpo, and is served a page by the web application server. when
+> the user submits their donation form, it's processed entirely by the
+> flask/django backend as opposed to the frontend javascript
+> validating the forum and submitting it to paypal/stripe. the web
+> application server could even request the currently active donation
+> perks, instead of a developer having to hack around javascript and
+> lektor every time the donation perks change
+>
+> of course, this would be a big change to donate, and would require a
+> non-trivial time investment for planning and building a web
+> application like this. i figured step 1 would be to create a ticket,
+> and we can go from there as the donate redesign progresses
+
+The idea of using Django instead of the previous custom PHP code split
+in multiple components was that a unified application would be more
+secure and less error-prone. In donate paleo, all of our form
+validation happened on the frontend. The middleware piece just passed
+the donation data to CiviCRM and hopes it's correct. CiviCRM seems to
+drop donations that don't validate, but I wouldn't rely on that to
+always drop invalid donations (and it did mean we silently lose
+"incorrect" donations instead of letting the user correct them).
+
+There was a debate between a CiviCRM-only implementation and the value
+of adding yet another "custom" layer in front of CiviCRM that we would
+have to maintain seemingly forever. In the end, we ended up keeping
+the Redis queue as an intermediate with CiviCRM, partly on [advice
+from our CiviCRM consultant](https://gitlab.torproject.org/tpo/web/donate-static/-/issues/107#note_2886312).
+
 ## Security and risk assessment
 
 ### django
@@ -489,12 +563,18 @@ the same manner.
 
 ## Proposed Solution
 
-No formal proposal (i.e. TPA-RFC) was established to build this
-service, but a [discussion happened for the first prototype](https://gitlab.torproject.org/tpo/web/donate-static/-/issues/107).
+No upcoming major changes are currently on the table for this
+service. As of August 2023, we're launching the site and have our
+hands full with that.
 
 ## Other alternatives
 
-None discussed so far, but see [tpo/web/donate-neo#20](https://gitlab.torproject.org/tpo/web/donate-neo/-/issues/20).
+None discussed so far, but see [tpo/web/donate-neo#20](https://gitlab.torproject.org/tpo/web/donate-neo/-/issues/20) and
+https://gitlab.torproject.org/tpo/web/donate-static/-/issues/107.
+
+### CiviCRM-only implementation
+
+- mathieu's inlay: https://gitlab.torproject.org/tpo/web/donate-static/-/issues/107#note_2872743
 
 ### Donate paleo legacy architecture