Add ADaaS documentation.

fern/docs/img/adaas/adaas-architecture.mmd

@@ -0,0 +1,21 @@
+---
+title: ADaaS architecture high-level overview
+---
+graph TB
+externalSystem[External system]
+worker([Worker])
+s3interact[s3interact]
+airdrop[Airdrop]
+s3[(AWS S3)]
+
+	externalSystem <-- Get/create users, issues, ... --> worker
+
+	worker <-- Exchange artifact upload/download URLs --> s3interact
+	worker <-- Upload/download artifacts --> s3
+	worker <-- ADaaS messages and REST API --> airdrop
+
+
+	subgraph DevRev
+	s3interact <-- Prepare upload/download URL --> s3
+	airdrop <-- Download/upload artifacts --> s3
+	end

fern/docs/img/adaas/adaas-extraction-phases.mmd

@@ -0,0 +1,53 @@
+---
+title: Extraction Phases
+---
+sequenceDiagram
+  actor user as UI
+  participant gw as Gateway
+  participant ad as Airdrop components
+  participant ee as External extractor
+
+	note over gw,ad: Extract External Sync Units
+	user ->> gw: Select import connection
+	gw ->> ad: Start External Sync Unit extraction
+	ad ->> ee: Start External Sync Unit extraction
+	ee -->> gw: List of External Sync Units
+	gw ->> ad: List of External Sync Units
+	ad ->> gw: List of External Sync Units
+	gw -->> user: Show available External Sync Units
+
+
+	note over gw,ad: Extract Metadata
+	ad ->> ee: Start Metadata extraction
+	ee -->> gw: List of extracted metadata artifacts
+	gw ->> ad: List of extracted metadata artifacts
+
+	note over gw,ad: Extract data
+	ad ->> ee: Start data extraction
+	ee -->> gw: List of extracted data artifacts
+	gw ->> ad: List of extracted data artifacts
+
+	note over ad: Transform and import data into DevRev
+
+	note over gw,ad: Extract attachments
+	ad ->> ee: Start attachment extraction
+	ee -->> gw: List of extracted attachments
+	gw ->> ad: List of extracted attachments
+
+	ad -->> gw: Finished import
+	gw -->> user: Show finished import and report
+
+	note over gw,ad: Delete data
+	user ->> gw: Delete import
+	gw ->> ad: Delete import
+	ad ->> ee: Delete data
+	ee -->> gw: Finished deleting data
+	gw ->> ad: Finished deleting data
+
+	note over gw,ad: Delete attachments
+	ad ->> ee: Delete attachments
+	ee -->> gw: Finished deleting attachments
+	gw ->> ad: Finished deleting attachments
+	note over ad: Deletes internal data
+	ad -->> gw: Finished deleting import
+	gw -->> user: Import deleted

fern/docs/pages/adaas/delete-phases.mdx

@@ -0,0 +1,28 @@
+During the delete phases, the snap-in may clean up its state or other side effects in the third party systems.
+In the most common extraction use cases, there is nothing to do and snap-ins may reply with the completion message.
+
+## Data deletion
+
+### Triggering event
+
+Airdrop initiates the data delete phase when the sync is deleted from DevRev.
+It is started by sending the worker a message with eventType: `EXTRACTION_DATA_DELETE`.
+
+### Snap-in response
+
+The worker must respond to Airdrop with a message with eventType `EXTRACTION_DATA_DELETE_DONE` when done or
+`EXTRACTION_DATA_DELETE_ERROR` in case of an error.
+
+## Attachments deletion
+
+
+### Triggering event
+
+Airdrop initiates the attachments delete phase when the Sync is deleted from DevRev.
+It is started by sending the span-in a message with eventType: `EXTRACTION_ATTACHMENTS_DELETE`.
+
+### Snap-in response
+
+The snap-in must respond to Airdrop with a message with eventType `EXTRACTION_ATTACHMENTS_DELETE_DONE` when done,
+or `EXTRACTION_ATTACHMENTS_DELETE_ERROR` in case of an error.
+

fern/docs/pages/adaas/extracting-attachments.mdx

@@ -0,0 +1,64 @@
+For the attachment extraction phase of the import process, the extractor has to upload each attachment to DevRev’s S3 using the `S3Interact` API.
+
+## Triggering event
+
+Airdrop initiates the Attachment Extraction by starting the snap-in with a message with eventType `EXTRACTION_ATTACHMENTS_START`
+when transitioning to the Data Extraction phase.
+
+During the Attachment Extraction phase,
+the snap-in extracts attachments from the External System and uploads them as Artifacts to DevRev.
+
+The snap-in must respond to Airdrop with a message with eventType `EXTRACTION_ATTACHMENTS_PROGRESS` together with an optional progress estimate and relevant Artifacts
+when it extracts some data and the maximum snap-in runtime (12 minutes) has been reached.
+
+The snap-in must respond to Airdrop with a message with eventType `EXTRACTION_ATTACHMENTS_DELAY` and specify a back-off time
+when the extraction has been rate-limited by the External System and back-off is required.
+
+In both cases, Airdrop starts the snap-in with a message with eventType `EXTRACTION_ATTACHMENTS_CONTINUE`.
+The restart is immediate (in case of `EXTRACTION_ATTACHMENTS_PROGRESS`) or delayed
+(in case of `EXTRACTION_ATTACHMENTS_DELAY`).
+
+Once the Attachment Extraction phase is done, the snap-in must respond to Airdrop with a message with eventType `EXTRACTION_ATTACHMENTS_DONE`.
+
+If Attachment Extraction failed, the snap-in must respond to Airdrop with a message with eventType `EXTRACTION_ATTACHMENTS_ERROR`.
+
+## Snap-in response
+
+After uploading an attachment or a batch of attachments, the extractor also has to prepare and upload a file specifying
+the extracted and uploaded attachments.
+
+It should contain the DevRev IDs of the extracted and uploaded attachments, along with the parent domain object ID
+from the external system and the actor ID from the external system.
+
+The uploaded artifact is structured like a normal artifact containing extracted data in JSON Lines format with specifying the
+`ssor_attachment` as an item type.
+
+## Examples
+
+Here is an example of an SSOR attachment file:
+```json
+[
+	{
+		"id": {
+			"external": "don:core:dvrv-us-1:devo/1:artifact/1" // The DON of the uploaded artifact
+		},
+		"parent_id": {
+			"external": "12345", // ID of the parent in the source system
+		},
+		"actor_id": {
+			"external": "123456", // ID of the uploader in the source system
+		}
+	},
+	{
+		"id": {
+			"external": "don:core:dvrv-us-1:devo/1:artifact/2" // The DON of the uploaded artifact
+		},
+		"parent_id": {
+			"external": "12344", // ID of the parent in the source system
+		},
+		"actor_id": {
+			"external": "123457", // ID of the uploader in the source system
+		}
+	}
+]
+```