docs: Add Mermaid diagrams to document system processes

README.md

@@ -49,3 +49,76 @@ You need to set up the following secrets in your GitHub repository settings:
 
 3.  **`SCRIPT_ID`**:
     - ID of script in script.google.com to deploy to (Sheets > Addons > Apps Script > id in url)
+## Processes
+
+### 1. User Creation
+
+This sequence diagram illustrates the workflow of creating a new user account from a business perspective.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Applicant
+    actor Superior
+    actor Admin
+
+    Applicant->>Admin: Submits registration form
+    Admin->>Superior: Sends email asking to verify the applicant
+    Superior->>Admin: Confirms applicant's identity via email link
+    Admin->>Admin: Reviews the confirmed request
+    Admin->>Applicant: Creates account and sends welcome email with credentials
+```
+
+### 2. Applications Cleanup (`freshCleanup`)
+
+This flowchart details the cleanup process, which ensures the organization is not cluttered with abandoned requests or inactive accounts.
+
+```mermaid
+flowchart TD
+    Start([Scheduled Cleanup]) --> CheckRequests[Check Unconfirmed Requests]
+
+    CheckRequests --> RequestLoop{For each request}
+    RequestLoop -->|Exactly 7 days old?| Reject[Reject request]
+    Reject --> EmailApplicant[Send rejection email to Applicant]
+    RequestLoop -->|Other| CheckAccounts[Check Fresh Accounts]
+
+    EmailApplicant --> CheckAccounts
+
+    CheckAccounts --> AccountLoop{For each 7-21 days old account}
+    AccountLoop -->|Never logged in?| Delete[Delete account]
+    AccountLoop -->|Logged in| Next[Skip]
+
+    Delete --> End([End])
+    Next --> End
+```
+
+### 3. Cyclic Account Deactivation (`scheduleForDeactivation` & `oldCleanup`)
+
+This sequence diagram explains the periodic cleanup of inactive accounts. Users must revalidate their active status every 2 years.
+
+**Important distinction:** Unlike new account creation where the superior is known, older accounts might have a new superior. Therefore, the Admin sends the verification link to the User, who must forward it to their current Superior to confirm their status.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Admin
+    actor User
+    actor Superior
+
+    %% Scheduling Phase
+    Admin->>User: Sends warning: "Account requires reconfirmation" (30 days deadline)
+
+    %% Reconfirmation Phase (User Action)
+    User->>Superior: Forwards the verification link to current Superior
+    Superior->>Admin: Clicks link & confirms User's active status
+    Admin->>User: Sends success email: "Account Reconfirmed"
+
+    %% Periodic Cleanup Phase (If not reconfirmed)
+    loop Every few days
+        alt 14, 7, or 1 days left
+            Admin->>User: Sends reminder email
+        else Deadline passed
+            Admin->>User: Suspends account and sends suspension email
+        end
+    end
+```