Create "Harper Applications in Depth" Learn Guide

learn/getting-started/create-your-first-application.mdx

@@ -5,6 +5,9 @@ title: Create Your First Application
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
+import HarperArchitectureDiagram from '../../src/components/learn/harper-architecture-diagram.mdx';
+import BasicAuthentication from '../../src/components/learn/basic-authentication.mdx';
+
 With Harper successfully installed and setup, let's dive into building your first Harper Application, a simple REST API. Harper lets you build powerful APIs with minimal effort.
 
 ## What You Will Learn
@@ -24,22 +27,7 @@ With Harper successfully installed and setup, let's dive into building your firs
 
 Before diving into building your first Harper application, it is important to understand a bit about Harper's architecture. The simplest way to think about Harper is as a stack.
 
-```
-┏━━━━━━━━━━━━━━━━━━┓
-┃ Applications     ┃
-┠──────────────────┨
-┃ Plugins          ┃
-┃  - rest          ┃
-┃  - graphqlSchema ┃
-┃  - ...           ┃
-┠──────────────────┨
-┃ Core Services:   ┃
-┃  - database      ┃
-┃  - networking    ┃
-┃  - component     ┃
-┃    management    ┃
-┗━━━━━━━━━━━━━━━━━━┛
-```
+<HarperArchitectureDiagram />
 
 At the bottom are the **core services** that make up the foundation of the Harper platform. This includes the high-performance **database**, extensible **networking** middleware, and **component** management system. Components are extensions of the core Harper system, and are further classified as **plugins** and **applications**.
 
@@ -220,13 +208,28 @@ If you need to check your work, checkout the [`02-rest-api`](https://github.com/
 
 With everything in place, now its time to create your first record for the `Dog` table.
 
-With the automatic REST API generation you have a plethora of options for interacting with the `Dog` table. We'll keep it simple for now, but will explore everything this has to offer in later guides.
+The goal is to create a new `Dog` record with an ID of `001` and the properties:
 
-Create a `PUT` request using the REST API port and the path `/Dog/001`. Include a JSON body with the specified attributes except for `id`. The `001` in the URL will be used as the ID for this entry.
+```json
+{
+	"name": "Harper",
+	"breed": "Black Labrador / Chow Mix",
+	"age": 5
+}
+```
 
-:::note
-If you're using Fabric remember to replace the `localhost` with your cluster's URL
-:::
+With the automatic REST API generation you enabled in the previous step, you now have a plethora of options for interacting with the `Dog` table.
+
+Fabric users should use the UI directly, but can optionally follow along with the following request snippets if they want. Importantly, Fabric users must do things differently:
+
+1. Replace `http://localhost` with their Fabric instance's URL
+2. Include an Authorization header in the requests.
+
+Here is some additional information on how to create a Basic Authentication token:
+
+<BasicAuthentication />
+
+Create a `PUT` request using the REST API port and the path `/Dog/001`. Include a JSON body with the specified attributes except for `id`. The `001` in the URL will be used as the ID for this entry.
 
 <Tabs groupId="http-client">
   <TabItem value="curl">
@@ -264,7 +267,7 @@ console.log(response.status);
   </TabItem>
 </Tabs>
 
-If you see `204` status code, then the record was successfully created!
+If you see a `204` status code, then the record was successfully created!
 
 ## Read a Record
 

src/components/learn/basic-authentication-v5.mdx

@@ -0,0 +1,50 @@
+{/* Due to a bug in prettier formatting (https://github.com/prettier/prettier/issues/17700) we can't retain multi-line comments with empty lines. */}
+{/* So instead, just store this edition of this component in a separate file until we get to update. */}
+{/* Replace `basic-authentication.mdx` with this when we switch from using `atob()` here https://github.com/HarperFast/harper/blob/main/security/auth.ts#L181 potentially in v5 */}
+
+<details>
+	<summary>Basic Authentication</summary>
+
+The simplest authorization scheme is [Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Authentication#basic_authentication_scheme) which transmits credentials as username/password pairs encoded using base64. Importantly, this scheme does not encrypt credentials. If used over an insecure connection, such as HTTP, they are susceptible to being compromised. Only ever use Basic Authentication over secured connections, such as HTTPS. Even then, its better to upgrade to an encryption based authentication scheme or certificates. Harper supports many different authentication mechanisms, and they will all be covered in later Learn guides.
+
+Use the username and password values from the previous [Install and Connect](/learn/getting-started/install-and-connect-harper) guide to generate an authorization value. The important part is to combine the `username` and `password` using a colon `:` character, encode that using base64, and then append the result to `"Basic "`.
+
+Here are some efficient methodologies:
+
+{/* Maybe consider using Tabs here with labels like "Node.js <=v24" and ("Web" or "Winter" or "W/MCA" if defined that abbreviation earlier somehow?) */}
+
+In Node.js v24 or earlier use the [`Buffer`](https://nodejs.org/docs/latest/api/buffer.html) API:
+
+```typescript
+// Ensure you replace these with your installation's values
+const username = 'HDB_ADMIN';
+const password = 'abc123!';
+const credentials = Buffer.from(`${username}:${password}`).toString('base64');
+const authorizationValue = `Basic ${credentials}`;
+```
+
+For Node.js v25 or later, most web browser consoles, and any WinterTC Minimum Common API compatible runtime use the [`Uint8Array.prototype.toBase64()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array/toBase64) API:
+
+```typescript
+// Ensure you replace these with your installation's values
+const username = 'HDB_ADMIN';
+const password = 'abc123!';
+const credentials = new TextEncoder().encode(`${username}:${password}`).toBase64();
+const authorizationValue = `Basic ${credentials}`;
+```
+
+> Both of these options are preferred over [`btoa()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/btoa) do to its limitation to Latin-1 character set.
+
+You would use the `authorizationValue` as the value for the `Authorization` header such as:
+
+```typescript
+fetch('/', {
+	// ...
+	headers: {
+		Authorization: authorizationValue,
+	},
+	// ...
+});
+```
+
+</details>

src/components/learn/basic-authentication.mdx

@@ -0,0 +1,26 @@
+<details>
+	<summary>Basic Authentication</summary>
+
+The simplest authorization scheme is [Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Authentication#basic_authentication_scheme) which transmits credentials as username/password pairs encoded using base64. Importantly, this scheme does not encrypt credentials. If used over an insecure connection, such as HTTP, they are susceptible to being compromised. Only ever use Basic Authentication over secured connections, such as HTTPS. Even then, its better to upgrade to an encryption based authentication scheme or certificates. Harper supports many different authentication mechanisms, and they will all be covered in later Learn guides.
+
+Use the username and password values from the previous [Install and Connect](/learn/getting-started/install-and-connect-harper) guide to generate an authorization value. The important part is to combine the `username` and `password` using a colon `:` character, encode that using base64, and then append the result to `"Basic "`.
+
+```typescript
+const username = 'HDB_ADMIN';
+const password = 'abc123!';
+const authorizationValue = `Basic ${btoa(`${username}:${password}`)}`;
+```
+
+You would use the `authorizationValue` as the value for the `Authorization` header such as:
+
+```typescript
+fetch('/', {
+	// ...
+	headers: {
+		Authorization: authorizationValue,
+	},
+	// ...
+});
+```
+
+</details>

src/components/learn/harper-architecture-diagram.mdx

@@ -0,0 +1,16 @@
+```
+┏━━━━━━━━━━━━━━━━━━┓
+┃ Applications     ┃
+┠──────────────────┨
+┃ Plugins          ┃
+┃  - rest          ┃
+┃  - graphqlSchema ┃
+┃  - ...           ┃
+┠──────────────────┨
+┃ Core Services:   ┃
+┃  - database      ┃
+┃  - networking    ┃
+┃  - component     ┃
+┃    management    ┃
+┗━━━━━━━━━━━━━━━━━━┛
+```