Add ADaaS documentation.

Author: samod

fern/docs/pages/references/adaas/adaas_overview.mdx

@@ -0,0 +1,42 @@
+# Airdrop-as-a-Service (ADaaS)
+
+Airdrop-as-a-Service (ADaaS) as a system consists of the internal Airdrop components and a Worker (Extractor or Loader),
+which is a Snap-In with a predefined structure.
+These Workers (Extractors and Loaders) can be built by anyone, not just DevRevelers.
+
+It is useful to know how the system works though, so this section explains how ADaaS works at a high level.
+Message protocols and other specifics can be found in the Extractor and Loader sections.
+
+It’s also useful to know that Airdrop uses its own AWS S3 structure
+(and its own buckets) and that only Airdrop components have access to it.
+This means that Workers can’t access these buckets directly,
+which is why all their data has to be uploaded to DevRev through S3Interact.
+
+For clarity, Artifact API and Airdrop are shown as separate entities,
+even though they are both accessed through DevRev’s API.
+Worker is shown as external, to clarify that it is developed by third parties,
+even though it runs on DevRev’s infrastructure.
+
+```mermaid
+---
+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/pages/references/adaas/creating_a_keyring.mdx

@@ -0,0 +1,10 @@
+# Creating Keyrings
+
+Keyrings are a DevRev-specific mechanism for managing authentication for External Systems.
+They are called Connections in the DevRev app.
+
+They provide a secure way to store and manage credentials within your DevRev Snap-In.
+This eliminates the need to expose sensitive information like passwords
+or access tokens directly within your code or configuration files, enhancing overall security.
+
+Read more about Keyrings in the [developer documentation](https://developer.devrev.ai/snapin-development/references/keyrings).

fern/docs/pages/references/adaas/extracting_attachments.mdx

@@ -0,0 +1,39 @@
+# Attachment Extraction phase
+
+For the Attachment Extraction phase of the import process,
+the Extractor has to upload each Attachment to DevRev’s S3 using the using S3Interact. 
+
+After uploading an attachment or a batch of attachments, the Extractor also has to prepare and upload an SSOR attachment file.
+It should contain the DevRev IDs of the extracted attachments, along with the parent and actor IDs from the External System.
+This needs to be done because only the Extractor knows to what the attachment was attached in the External system.
+The SSOR attachment file should then be sent just like any normal Artifact, but with the `ssor_attachment` 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
+		}
+	}
+]
+```

fern/docs/pages/references/adaas/extracting_data.mdx

@@ -0,0 +1,15 @@
+# Data Extraction Phase
+
+In the data extraction phase, the Extractor is expected to call the External System’s APIs
+to retrieve all the items that were updated since the start of the last extraction.
+If there was no previous extraction (the current run is an Initial Import), then all the items should be extracted.
+The Extractor should remember at what time it started each extraction,
+so that it can extract only items created and/or updated since this date in the next extraction run.
+The reason for remembering it at the start of the extraction, and not at the end, is to allow some overlap
+in case the items are updated during extraction (which happens very often in bigger organizations).
+
+Each batch of extracted items (the recommended batch size is 2000-5000 items) must be formatted in JSONL
+(JSON Lines format), gzipped, and submitted as an Artifact to S3Interact (with tooling from `@devrev/adaas-sdk`).
+
+Each Artifact is submitted with an `item_type`, defining a separate domain object from the External System.
+Item types defined when uploading extracted data must match those in the Initial Domain Mapping Artifact.

fern/docs/pages/references/adaas/extracting_external_sync_units.mdx

@@ -0,0 +1,27 @@
+# Extract External Sync Units Phase
+
+In the External Sync Unit extraction phase, the Extractor is expected to get the list of projects, repositories, etc.
+(whatever the equivalent of those is called in the External System)
+that it can extract with the provided credentials and send it to Airdrop in its response.
+
+The most important structure in the message is the list of External Sync Units (event_data.external_sync_units in JSON),
+which contains the following fields:
+- ID: This is the unique identifier in the External System
+- Name: This is the human-readable name in the External System
+- Description: A short description if the External System provides it
+- Item count (item_count): The number of items (issues, tickets, comments, etc.) in the External System,
+if it can be obtained in a very lightweight manner, such as by calling a special API endpoint.
+If there is no such way to get it, i.e., the items would need to be extracted to count them,
+then the item count should be `-1`, to avoid blocking the import with long-running queries.
+
+Example:
+```json
+[
+  {
+    "id": "a-microservice-repository",
+    "name": "A Microservice Repository",
+    "description": "Our greatest microservice repo",
+    "item_count": 232
+  }
+]
+```