From e946be8b6ecc24718dc72b774bc89948f551369e Mon Sep 17 00:00:00 2001
From: krisantrobus <55083528+krisantrobus@users.noreply.github.com>
Date: Wed, 29 Jan 2025 14:27:51 -0600
Subject: [PATCH] chore(intenral-docs): add icons doc (#4215)

* chore(intenral-docs): add icons doc

* chore(internal-docs): backend development

* chore(internal-docs): update backend docs

* chore(internal-docs): fix typo

---------

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
---
 .../engineering/developing-locally.md         | 70 +++++++++++++++++++
 internal-docs/engineering/icons.md            | 21 ++++++
 package.json                                  |  1 +
 3 files changed, 92 insertions(+)
 create mode 100644 internal-docs/engineering/icons.md

diff --git a/internal-docs/engineering/developing-locally.md b/internal-docs/engineering/developing-locally.md
index 9a28a8570f..55496823fc 100644
--- a/internal-docs/engineering/developing-locally.md
+++ b/internal-docs/engineering/developing-locally.md
@@ -13,6 +13,7 @@
   - [Working on components](#working-on-components)
   - [Working on the docs site](#working-on-the-docs-site)
   - [Working on Remix (Theme Designer)](#working-on-remix-theme-designer)
+  - [Working on Backend](#working-on-backend)
 
 ## Prerequisites
 
@@ -300,3 +301,72 @@ Then run:
 ```bash
 yarn start:theme-designer
 ```
+
+## Working on Website Backend
+
+This section covers how to setup the Supabase backend and configuring additional environment variables. This will enable development of AI assistant and generation scripts such as [generate-embeddings.ts](../../packages/paste-website/scripts/search/generate-embeddings.ts) 
+
+### Prerequisites
+
+You will need docker or a similar service in order to start the local supabase instance.
+
+### Environment
+
+To run the backend and develop all functionality of the website you will need to add additional variable in the `.env` file previously configured
+
+**Note**: access can be granted internally to OpenAI via the Service portal
+
+<table>
+  <tr>
+   <td>OPENAI_API_KEY
+   </td>
+   <td>The token used to interact with OpenAI
+   </td>
+  </tr>
+  <tr>
+   <td>OPENAI_API_SECRET
+   </td>
+   <td>The secret provided by OpenAI
+   </td>
+  </tr>
+  <tr>
+   <td>OPENAI_ASSISTANT_ID
+   </td>
+   <td>The assistant id for the OpenAI project
+   </td>
+  </tr>
+  <tr>
+   <td>SUPABASE_URL
+   </td>
+   <td>The url of the supabase backend you want to use. For local development is should map to <strong>http://127.0.0.1:54321</strong>
+   </td>
+  </tr>
+  <tr>
+   <td>SUPABASE_KEY
+   </td>
+   <td>This will be generated and output from the start command in `/apps/backend`. It can also be retrieved by running `npx supabase status` in the directory.
+   </td>
+  </tr>
+  <tr>
+   <td>GH_SERVICE_ACC_DISCUSSIONS_TOKEN
+   </td>
+   <td>Used for embeddings script, must be a token with read access to Paste repo discussions.
+   </td>
+  </tr>
+  <tr>
+   <td>ROLLBAR_ACCESS_TOKEN
+   </td>
+   <td>A dummy value can be used for local development e.g. "MOCK_TOKEN"
+   </td>
+  </tr>
+</table>
+
+### Running Supabase
+
+Supabase is the data storage layer used by the application. We use it to store messages with the Paste AI Assistant and also storing embeddings used by our search functionality for pages and GitHub discussions.
+
+With Docker or a similar service running, you can start supabase by running `start:backend:dev`. This will output details of the envirnment such as auth tokens used to connect to the APIs and URLs of the frontent and services.
+
+You should be able to access the UI at http://localhost:54323.
+
+Migrations should be applied by default. If there are no tables on startup run the `db:reset` command in the `apps/backend` directory.
\ No newline at end of file
diff --git a/internal-docs/engineering/icons.md b/internal-docs/engineering/icons.md
new file mode 100644
index 0000000000..4918f3ae37
--- /dev/null
+++ b/internal-docs/engineering/icons.md
@@ -0,0 +1,21 @@
+# Icons
+
+- [Icons](#icons)
+  - [Adding Icons](#adding-icons)
+  - [Generating Icons](#generating-icons)
+
+Our icons are converted from SVG to React components at compile time using our own “svg-to-react” library: [https://github.com/twilio-labs/svg-to-react](https://github.com/twilio-labs/svg-to-react)
+
+## Adding Icons
+
+The process for adding icons is very simple thanks to our naming conventions and conversion library.
+
+Any new SVG assets must be copied into the [svg](../../packages/paste-icons/svg/) folder. We often see the `viewBox` attribute missing so be sure the top level element has the following:
+
+```html
+<svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+```
+
+## Generating Icons
+
+To generate newly added icons you can use the command `yarn convert:icons:new` from the root of the repo. This will create the new React components and appends the "Icon" string to the component name.
diff --git a/package.json b/package.json
index 9fc6055845..6121766806 100644
--- a/package.json
+++ b/package.json
@@ -51,6 +51,7 @@
     "generate:embeddings:refresh": "yarn nx run @twilio-paste/website:generate:embeddings:refresh",
     "generate:db-types": "yarn nx run @twilio-paste/backend:generate:db-types",
     "generate:website-data": "yarn workspace @twilio-paste/website fetch:data",
+    "convert:icons:new": "yarn workspace @twilio-paste/icons convert-new",
     "pre-push": "concurrently \"yarn:lint\" \"yarn:test\" \"yarn:format\" \"yarn:type-check\"",
     "prerelease": "yarn build && yarn generate:website-data && yarn lint && yarn test",
     "release": "yarn changeset publish",