From c6b39a18527dcbfc70d1a237042b71b2dab71456 Mon Sep 17 00:00:00 2001
From: Nick Mango <wanyaland+nickmango@gmail.com>
Date: Wed, 4 Dec 2024 13:40:42 +0300
Subject: [PATCH] Feature/Contributor Sequence flow

- Added markdown for sequence flow for a contributor who is gated

Signed-off-by: Nick Mango <wanyaland+nickmango@gmail.com>
---
 docs/contributor-api.md | 118 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 docs/contributor-api.md

diff --git a/docs/contributor-api.md b/docs/contributor-api.md
new file mode 100644
index 000000000..c004f6678
--- /dev/null
+++ b/docs/contributor-api.md
@@ -0,0 +1,118 @@
+```
+# EasyCLA Sign Flow: Sequence Overview
+
+## 1. User Creates a Pull Request (PR)
+- A contributor initiates a PR in the repository hosted on GitHub, Gerrit, or GitLab.
+
+## 2. Repository Triggers Activity Endpoint
+- The repository platform sends a request to EasyCLA's Python endpoint:
+  ```
+  v2/repository-provider/{provider}/activity
+  ```
+
+## 3. EasyCLA Checks User Authorization
+- EasyCLA internally verifies if the users involved in the PR are authorized to contribute to the repository.
+
+## 4. Update Repository with User Status
+- EasyCLA communicates back to the repository provider, updating the status of each user as either **signed** or **not signed**.
+
+## 5. User Initiates Sign Process
+- If a user is marked as **not signed**, they are prompted to begin the signing process and are redirected to the **EasyCLA Contributor Console**.
+
+## 6. Contributor Chooses Sign Type
+- Upon reaching the Contributor Console, the user selects one of two options:
+  - **Individual Contributor**
+  - **Corporate Contributor**
+
+---
+
+## 7. Individual Contributor Flow
+
+### a. Initiate Individual Signature Request
+- The system invokes the Go-based endpoint:
+  ```
+  v4/request-individual-signature
+  ```
+- This action creates a new signature record with `signed = false` and initiates the signing process.
+
+### a1. Redirect to DocuSign
+- The API handles the integration with DocuSign, preparing a callback and redirect URL, and redirects the user to DocuSign for signing.
+
+### a2. Completion of Signing
+- Once the user completes the signing on DocuSign, a callback is triggered to:
+  ```
+  v4/signed/individual/{installation_id}/{github_repository_id}/{change_request_id}
+  ```
+- This endpoint updates the signature record's `signed` flag to **true**, completing the process.
+
+---
+
+## 8. Corporate Contributor Flow
+
+### b. Initiate Corporate Signature Process
+
+#### 1. Redirect to Company Search
+- The user is redirected to a company search interface within the Contributor Console.
+
+#### 2. Search for Company
+- Upon selecting a company, the system calls the Go-based search endpoint:
+  ```
+  v3/organization/search?companyName=<company_name>&include-signing-entity-name=false
+  ```
+- This retrieves the relevant company information.
+
+#### 3. Check and Prepare Employee Signature
+- The system invokes the Python endpoint:
+  ```
+  v2/check-prepare-employee-signature
+  ```
+- This checks whether the company follows a **Corporate CLA (CCLA)** or an **Entity CLA (ECLA)** flow.
+
+---
+
+### i. If Company Has a CCLA:
+- The system verifies if the user is authorized:
+  - **If not authorized:**
+    - Prompts the user to contact the existing CLA manager for authorization.
+    - Sends a notification to CLA managers via the Go-based endpoint:
+      ```
+      v4/notify-cla-managers
+      ```
+    - An email is sent to the CLA managers, and the process ends.
+  - **If authorized:**
+    - Calls:
+      ```
+      v4/request-employee-signature
+      ```
+
+---
+
+### ii. If Company Does Not Have a CCLA:
+- The system checks if the user is a CLA manager:
+  - **A. User is a CLA Manager:**
+    - Assigns CLA manager designee permissions via:
+      ```
+      v4/company/{companySFID}/user/{userLFID}/claGroupID/{claGroupID}/cla-manager-designee
+      ```
+    - Verifies the assigned role:
+      ```
+      v4/company/{companySFID}/user/{userLFID}/claGroupID/{claGroupID}/is-cla-manager-designee
+      ```
+    - Redirects to the corporate console where the user can see the **Sign** button.
+    - Calls the endpoint to request a corporate signature:
+      ```
+      v4/request-corporate-signature
+      ```
+    - This creates the signature record, completing the process.
+
+  - **B. User is Not a CLA Manager:**
+    - Fetches company administrators using:
+      ```
+      v4/company/{companySFID}/admin
+      ```
+    - Sends an invitation to become a company admin via:
+      ```
+      /user/{userID}/invite-company-admin
+      ```
+    - An email is sent to the user to invite them as a company admin, concluding the process.
+```
\ No newline at end of file