From 2f1aa37052cf47f22cd89ef4a2ae48635fd7c4fa Mon Sep 17 00:00:00 2001
From: Clark Alesna <clark_alesna@hotmail.com>
Date: Mon, 7 Oct 2024 23:47:05 +0800
Subject: [PATCH] docs: add graphql backend api info (#63)

---
 docs/.gitignore                   |   1 +
 docs/pages/guides/_meta.json      |   5 +-
 docs/pages/guides/backend_api.mdx | 105 ++++++++++++++++++++++++++++++
 3 files changed, 110 insertions(+), 1 deletion(-)
 create mode 100644 docs/pages/guides/backend_api.mdx

diff --git a/docs/.gitignore b/docs/.gitignore
index b90a368..9e1205c 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,2 +1,3 @@
 node_modules
 .next
+bun.lockb
\ No newline at end of file
diff --git a/docs/pages/guides/_meta.json b/docs/pages/guides/_meta.json
index cfa4d54..ab4fa39 100644
--- a/docs/pages/guides/_meta.json
+++ b/docs/pages/guides/_meta.json
@@ -1,4 +1,7 @@
 {
   "creating_ship": "Creating a Ship",
-  "moving_ship": "Moving a Ship"
+  "moving_ship": "Moving a Ship",
+  "gathering_fuel": "Gathering Fuel",
+  "mining_asteria": "Mining Asteria",
+  "backend_api": "Backend API"
 }
diff --git a/docs/pages/guides/backend_api.mdx b/docs/pages/guides/backend_api.mdx
new file mode 100644
index 0000000..8438e75
--- /dev/null
+++ b/docs/pages/guides/backend_api.mdx
@@ -0,0 +1,105 @@
+# Querying the Backend API
+
+Project Asteria provides a `GraphQL` API to query the state of the game. The primary query used is `objectsInRadius`, which retrieves objects within a specified radius around a given point.
+
+## Example Query
+
+Below is an example of a query to get objects around the center point (0,0) with a radius of 10:
+
+```graphql
+query getObjects {
+  objectsInRadius(center: { x: 0, y: 0 }, radius: 10) {
+    ... on Ship {
+      __typename
+      id
+      position {
+        x
+        y
+      }
+    }
+    
+    ... on Fuel {
+      __typename
+      id
+      position {
+        x
+        y
+      }
+    }
+    
+    ... on Asteria {
+      __typename
+      id
+      position {
+        x
+        y
+      }
+    }
+  }
+}
+```
+
+## Example Response
+
+```json
+{
+  "data": {
+    "objectsInRadius": [
+      {
+        "__typename": "Fuel",
+        "id": "4e0016f77ce8a21423f6934d2d88f4cc8e2fb4f8f97c518d4514b0d3a2924f35#0",
+        "position": {
+          "x": 1,
+          "y": 3
+        }
+      },
+      {
+        "__typename": "Fuel",
+        "id": "ea172bf05a38f3957b0c0c6ba2a52475e0e0be4cd5e90b4e90af158f7fde3b2b#0",
+        "position": {
+          "x": 7,
+          "y": -1
+        }
+      },
+      {
+        "__typename": "Fuel",
+        "id": "761740a434acd2601cb363d5be6b979dd7fb270a6ba6d5f2a4f719e15bec693a#0",
+        "position": {
+          "x": -2,
+          "y": -8
+        }
+      },
+      {
+        "__typename": "Asteria",
+        "id": "fc6bec839c05a4ec687c42057818c0cb9b8fbd827b6779e2c06c63487439f95a#1",
+        "position": {
+          "x": 0,
+          "y": 0
+        }
+      }
+    ]
+  }
+}
+```
+
+A preview testnet `GraphQL` endpoint is available at [https://dmtr_scrolls_v0_preview_1t9nhgnmxtpzrzm2gwv0723cu.scrolls-m0.demeter.run/graphql](https://dmtr_scrolls_v0_preview_1t9nhgnmxtpzrzm2gwv0723cu.scrolls-m0.demeter.run/graphql).
+
+## Implementation Details
+
+The backend uses a SQL query with a Manhattan distance calculation to find objects within the specified radius. The query ensures that the objects are within the bounds defined by the radius and the center point.
+
+```rs
+let fetched_objects = sqlx::query_as!(MapObjectRecord,
+    "SELECT id, fuel, positionX as position_x, positionY as position_y, shipyardPolicy as policy_id, shipTokenName as token_name, pilotTokenName as pilot_name, class, totalRewards as total_rewards
+     FROM mapobjects
+     WHERE positionX BETWEEN ($1::int - $3::int) AND ($1::int + $3::int)
+     AND positionY BETWEEN ($2::int - $3::int) AND ($2::int + $3::int)
+     AND ABS(positionX - $1::int) + ABS(positionY - $2::int) <= $3::int
+     AND shipyardPolicy = $4::text",
+    center.x, center.y, radius, shipyard_policy_id.id.to_string()
+)
+```
+
+## Database and Projection
+
+The database consists of UTXOs in the smart contract validators. These UTXOs are projected into a materialized view using [Mumak](https://github.com/txpipe/mumak), a PostgreSQL extension that allows developers to project or filter CBOR data within PostgreSQL. The generated materialized view is queried by the backend API as if it were a regular table. This enables efficient distance queries over CBOR data directly within PostgreSQL.
\ No newline at end of file