update foundations content and link config

Author: jyecusch

docs/further-reading/how-devs-use-nitric.mdx

@@ -14,7 +14,7 @@ Projects can have as many service files as desired, and each one will map to a c
 
 The Nitric SDK offers a comprehensive set of tools, including handlers for events/topics, queues, storage, key-value (KV) stores, schedules, APIs and secrets. These components are the essential building blocks for building cloud applications.
 
-SDKs communicate with the Nitric Server using gRPC and Protocol Buffers, which enables the framework to support [many languages](/reference/languages). Resources defined in the SDK do not require low-level configuration, which means that application code will never contain parameters or annotations for config, such as the replication policies for data stores. This fine-grained control is handled by [Providers](/foundations/deployment/providers), which are described in the Ops workflow.
+SDKs communicate with the Nitric Server using gRPC and Protocol Buffers, which enables the framework to support [many languages](/reference/languages). Resources defined in the SDK do not require low-level configuration, which means that application code will never contain parameters or annotations for config, such as the replication policies for data stores. This fine-grained control is handled by [Providers](/foundations/deployment#providers), which are described in the Ops workflow.
 
 ## Local Cloud Emulation
 

docs/get-started/foundations/infrastructure/index.mdx

@@ -4,17 +4,18 @@ description: Nitric allows applications to declare infrastructure requirements a
 
 # Infrastructure
 
-Infrastructure from Code (IfC) is an extension of Infrastructure as Code (IaC) that takes runtime application code into consideration and enhances Separation of Concerns (SoC).
+If you haven't read [Why Nitric](/get-started/foundations/why-nitric) yet, you might want to start there. It explains the 'why' behind Nitric, which can help you understand the 'what' and 'how' of Nitric.
+
+Nitric applies the concept of Infrastructure from Code (IfC) in a very specific way, to enhance Infrastructure as Code (IaC) and help applications with platform specific Separation of Concerns (SoC).
 
 <Note>
-  Several products describe themselves as "Infrastructure from Code" (IfC), but
-  they're not all like Nitric. Many are platforms/SaaS products, not a
-  framework. Those products have different benefits and trade-offs.
+  "Infrastructure from Code" (IfC) is an emerging term and sometimes refers to
+  proprietary platforms/SaaS products. Instead, Nitric is an open source
+  application framework, that integrates with existing IaC tools, to automate
+  the creation of infrastructure from application code.
 </Note>
 
-Nitric's Infrastructure from Code (IfC) automates the creation of infrastructure from your application code, ensuring a clear separation between application logic and deployment concerns.
-
-It abstracts the infrastructure layer, allowing developers to define what their application needs without getting bogged down in the specifics of cloud services or infrastructure configurations.
+Nitric separates platform-specific cloud and infrastructure interaction away from core application code, while allowing developers to define their application's requirement explicitly.
 
 Sometimes it's easier to explain IfC by exploring the benefits.
 
@@ -28,41 +29,201 @@ Nitric significantly reduces or removes cloud-specific code. For example, access
 
 <TabItem label="Nitric SDK">
 
-```javascript
+This code works equally with AWS S3, Google Cloud Storage, Azure Blob Storage, or any other storage service:
+
+<CodeSwitcher tabs>
+
+```javascript !!
+import { bucket } from '@nitric/sdk'
+
+const receiptDocs = bucket('receipt-docs').allow('read')
+
+export async function getReceiptDoc(filename) {
+  return await receiptDocs.file(filename).read()
+}
+```
+
+```typescript !!
 import { bucket } from '@nitric/sdk'
 
-const profiles = bucket('profiles').allow('read')
+const receiptDocs = bucket('receipt-docs').allow('read')
 
-export const getProfilePic = async (filename) => {
-  return await profiles.file(filename).read()
+export async function getReceiptDoc(filename: string): Promise<Uint8Array> {
+  return await receiptDocs.file(filename).read()
 }
 ```
 
+```python !!
+from nitric.resources import bucket
+
+receipts_docs = bucket("receipts").allow("read")
+
+async def get_receipt_doc(filename):
+  return await receipts_docs.file(filename).read()
+
+```
+
+```go !!
+import (
+	"context"
+
+	"github.com/nitrictech/go-sdk/nitric"
+	"github.com/nitrictech/go-sdk/nitric/storage"
+)
+
+var receiptDocs storage.BucketClient
+
+func init() {
+	receiptDocs = *nitric.NewBucket("receipt-docs").Allow(storage.BucketRead)
+}
+
+func getReceiptDoc(ctx context.Context, filename string) ([]byte, error) {
+	return receiptDocs.Read(ctx, filename)
+}
+```
+
+```dart !!
+import 'package:nitric_sdk/nitric.dart';
+
+final receiptDocs = Nitric.bucket("receipt-docs").allow([
+  BucketPermission.read,
+]);
+
+Future<List<int>> getReceiptDoc(String filename) async {
+  return await receiptDocs.file(filename).read();
+}
+```
+
+</CodeSwitcher>
+
 </TabItem>
 
 <TabItem label="AWS SDK">
 
-```javascript
+This code is specific to AWS S3 and requires additional runtime setup and error handling:
+
+<CodeSwitcher tabs>
+
+```javascript !!
+import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3'
+
+const s3 = new S3Client({})
+const RECEIPT_DOCUMENTS_BUCKET = process.env.RECEIPT_DOCUMENTS_BUCKET
+
+if (!RECEIPT_DOCUMENTS_BUCKET) {
+  throw new Error('RECEIPT_DOCUMENTS_BUCKET environment variable not set')
+}
+
+export async function getReceiptDoc(filename) {
+  const command = new GetObjectCommand({
+    Bucket: RECEIPT_DOCUMENTS_BUCKET,
+    Key: filename,
+  })
+
+  const response = await s3.send(command)
+  return await response.Body.transformToByteArray()
+}
+```
+
+```typescript !!
 import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3'
 
-const client = new S3Client({})
-const PROFILES_BUCKET = process.env.PROFILES_BUCKET
+const s3 = new S3Client({})
+const RECEIPT_DOCUMENTS_BUCKET = process.env.RECEIPT_DOCUMENTS_BUCKET
 
-if (!bucket) {
-  throw new Error('PROFILES_BUCKET environment variable not set')
+if (!RECEIPT_DOCUMENTS_BUCKET) {
+  throw new Error('RECEIPT_DOCUMENTS_BUCKET environment variable not set')
 }
 
-export const getProfilePic = async (filename) => {
+export async function getReceiptDoc(filename: string): Promise<Uint8Array> {
   const command = new GetObjectCommand({
-    Bucket: PROFILES_BUCKET,
+    Bucket: RECEIPT_DOCUMENTS_BUCKET,
     Key: filename,
   })
 
-  const response = await client.send(command)
+  const response = await s3.send(command)
   return await response.Body.transformToByteArray()
 }
 ```
 
+```python !!
+import os
+import boto3
+
+RECEIPT_DOCUMENTS_BUCKET = os.getenv('RECEIPT_DOCUMENTS_BUCKET')
+
+if not RECEIPT_DOCUMENTS_BUCKET:
+    raise EnvironmentError('RECEIPT_DOCUMENTS_BUCKET environment variable not set')
+
+s3_client = boto3.client('s3')
+
+def get_receipt_doc(filename):
+    response = s3_client.get_object(Bucket=RECEIPT_DOCUMENTS_BUCKET, Key=filename)
+    return response['Body'].read()
+
+```
+
+```go !!
+package main
+
+import (
+	"context"
+	"os"
+	"github.com/aws/aws-sdk-go-v2/aws"
+	"github.com/aws/aws-sdk-go-v2/config"
+	"github.com/aws/aws-sdk-go-v2/service/s3"
+	"io"
+)
+
+var receiptDocumentsBucket = os.Getenv("RECEIPT_DOCUMENTS_BUCKET")
+
+func init() {
+	if receiptDocumentsBucket == "" {
+		panic("RECEIPT_DOCUMENTS_BUCKET environment variable not set")
+	}
+}
+
+func getReceiptDoc(filename string) ([]byte, error) {
+	cfg, _ := config.LoadDefaultConfig(context.TODO())
+	s3Client := s3.NewFromConfig(cfg)
+
+	resp, _ := s3Client.GetObject(context.TODO(), &s3.GetObjectInput{
+		Bucket: aws.String(receiptDocumentsBucket),
+		Key:    aws.String(filename),
+	})
+
+	defer resp.Body.Close()
+	return io.ReadAll(resp.Body)
+}
+```
+
+```dart !!
+import 'dart:io';
+import 'package:aws_s3_api/s3-2006-03-01.dart';
+
+final receiptDocumentsBucket = Platform.environment['RECEIPT_DOCUMENTS_BUCKET'];
+
+void checkBucketEnv() {
+  if (receiptDocumentsBucket == null || receiptDocumentsBucket!.isEmpty) {
+    throw Exception('RECEIPT_DOCUMENTS_BUCKET environment variable not set');
+  }
+}
+
+Future<List<int>> getReceiptDoc(String filename) async {
+  checkBucketEnv();
+  final client = S3(region: 'us-west-2'); // Adjust region
+  final request = GetObjectRequest(
+    bucket: receiptDocumentsBucket!,
+    key: filename,
+  );
+
+  final response = await client.getObject(request);
+  return await response.body.toBytes();
+}
+```
+
+</CodeSwitcher>
+
 </TabItem>
 
 </Tabs>
@@ -75,7 +236,9 @@ Nitric keeps application code independent of specific cloud services. Developers
 
 For example this same code would work equally well backed by AWS SNS, AWS EventBridge, Google Cloud Pub/Sub, Azure EventGrid, Apache Kafka, or any other messaging service:
 
-```javascript
+<CodeSwitcher tabs>
+
+```javascript !!
 import { topic } from '@nitric/sdk'
 
 const myTopic = topic('my-topic').allow('publish')
@@ -85,7 +248,59 @@ export const publishMessage = async (message) => {
 }
 ```
 
-We can change the underlying messaging service through a simple configuration change, without modifying the application code.
+```typescript !!
+import { topic } from '@nitric/sdk'
+
+const myTopic = topic('my-topic').allow('publish')
+
+export async function publishMessage(message: any) {
+  await myTopic.publish(message)
+}
+```
+
+```python !!
+from nitric.resources import topic
+
+my_topic = topic("my-topic").allow("publish")
+
+async def publish_message(message):
+    await my_topic.publish(message)
+```
+
+```go !!
+import (
+  "context"
+
+  "github.com/nitrictech/go-sdk/nitric"
+  "github.com/nitrictech/go-sdk/nitric/topics"
+)
+
+var myTopic topics.TopicClient
+
+func init() {
+  myTopic = *nitric.NewTopic("my-topic").Allow(topics.TopicPublish)
+}
+
+func publishMessage(ctx context.Context, message map[string]interface{}) error {
+  return myTopic.Publish(ctx, message)
+}
+```
+
+```dart !!
+import 'package:nitric_sdk/nitric.dart';
+
+final myTopic = Nitric.topic("my-topic").allow([
+  TopicPermission.publish,
+]);
+
+Future<void> publishMessage(Map<String, dynamic> message) async {
+  await myTopic.publish(message);
+}
+```
+
+</CodeSwitcher>
+
+We can change the underlying messaging service through a simple configuration change—which plugin to use, without modifying the application code.
 
 <Tabs>
 
@@ -136,7 +351,7 @@ provider: your_namespace/[email protected]
 
 ## Automate Application Infrastructure Requirements
 
-Using Infrastructure as Code (IaC) tools like Terraform, Pulumi, or AWS CDK, developers can define the infrastructure requirements for their application. You can even create reusable modules for common infrastructure patterns. For example, you could create a pattern for async messaging, which includes a topic, and a subscription bound to a compute function.
+Using Infrastructure as Code (IaC) tools like Terraform, Pulumi, or AWS CDK, developers can define the infrastructure requirements for their application. You can even create reusable modules for common infrastructure patterns. For example, you could create a pattern for async messaging, which includes a topic, and a subscription bound to a serverless function.
 
 The problem is that these tools in isolation require manual processes to keep the infrastructure in sync with the application code. Processes that are error-prone and time-consuming.
 
@@ -150,9 +365,11 @@ If you want to see the spec for your application you can run `nitric spec`:
 nitric spec
 ```
 
+This spec can be automatically forwarded to plugins that generate the IaC configuration and implement a runtime API adapter the chosen services. This way, the IaC configuration is always in sync with the application code and the code always works on the target platform.
+
 ### No Rogue Resources or Permissions
 
-Resources and access requirements are defined as close as possible to where they're used - so it's easy to see when they're no longer needed or permissions are too broad.
+Resources and access requirements are defined as close as possible to where they are used, making it easy to see when they are no longer needed or when permissions are too broad.
 
 ```javascript
 import { queue } from '@nitric/sdk'
@@ -174,10 +391,50 @@ The name of a resource is defined **_once_** (in the code), instead of twice (in
 sql('profiles')
 ```
 
-and the framework maps the requirements specification to plugins written with existing IaC tools. These tools are still responsible for provisioning the resources, roles, and permissions.
+Nitric maps the requirements specification to plugins written with existing IaC tools like Terraform, Pulumi or CloudFormation. These tools are still responsible for provisioning the resources, roles, and permissions, those things are never directly embedded in the application code.
 
 ### Don't Change App Code for Infrastructure Changes
 
-You haven't imported the AWS SDK, Google Cloud SDK, or Azure SDK. You haven't written any cloud-specific code. You haven't written any mocks or tests for these cloud services, or anything that makes your code less portable.
+At this point you haven't imported the AWS, Google Cloud, or Azure SDK. You haven't written any cloud-specific code in your application. You haven't written any mocks or tests for these cloud services, or anything that makes your code less portable.
+
+So when changes are needed for performance, cost, or compliance, you can make them instantly. Like we mentioned before, that part is just config.
+
+<Tabs>
+
+<TabItem label="AWS">
+
+```yaml title:nitric.prod.yaml
+provider: nitric/[email protected]
+```
+
+</TabItem>
+
+<TabItem label="Azure">
 
-So when changes are needed for performance, cost, or compliance, you can make them instantly. It's just a line of config.
+```yaml title:nitric.prod.yaml
+provider: nitric/[email protected]
+```
+
+</TabItem>
+
+<TabItem label="Google Cloud">
+
+```yaml title:nitric.prod.yaml
+provider: nitric/[email protected]
+```
+
+</TabItem>
+
+<TabItem label="Anything Else">
+
+```yaml title:nitric.prod.yaml
+provider: your_namespace/[email protected]
+```
+
+</TabItem>
+
+</Tabs>
+
+```bash
+nitric up
+```