edits

Author: jyecusch

docs/architecture/apis.mdx

@@ -2,23 +2,24 @@
 description: 'Nitric API'
 ---
 
-# APIS
+# APIs
 
 ## 1. System Context
 
-**Developers** use Nitric to declare APIs and routes within their application.
+**Developers** use Nitric to define required APIs and routes/methods within their application.
 
-- App code uses the [API resource](/apis) through defined endpoints.
-- Developers define API specifications and implement backend logic to handle HTTP requests.
+- App code uses the [API resource](/apis) to define APIs and their routes/methods.
+- Developers define API(s) their application requires, including the specifications and implement logic to handle HTTP requests.
+- Authentication, authorization, and middleware can be added to API routes to secure and enhance functionality.
 
-**Operations** use default or overridden Terraform modules to provision the necessary resources for their target cloud.
+**Operations** use default or overridden IaC (e.g Terraform modules) to provision the necessary resources for their target cloud(s), such as API Gateways.
 
 <details>
   <summary>Example AWS Provider</summary>
 
 - **AWS API Gateway v2** serves as the HTTP API management service.
 - **AWS Lambda** functions are deployed to handle API requests.
-- **AWS IAM** (implicitly assumed) provides roles and policies for secure interaction between API Gateway and Lambda functions.
+- **AWS IAM** (automated using IaC) provides roles and policies for secure interaction between API Gateway and Lambda functions.
 - **AWS ACM** manages TLS certificates for custom domain names.
 
 ```mermaid
@@ -118,7 +119,7 @@ sequenceDiagram
 
 ## 4. Code
 
-**Developers** write application code that uses the [API resource](/apis) from the SDK, configures the api and implement HTTP routes and middleware.
+**Developers** write application code that uses the [API resource](/apis) from the SDK, defining the APIs routes, methods, middleware and auth.
 
 SDK Reference by language -
 

docs/architecture/buckets.mdx

@@ -2,25 +2,25 @@
 description: 'C4 Buckets'
 ---
 
-# Storage - Buckets
+# Storage (Buckets/Object Storage)
 
 ## 1. System Context
 
-**Developers** use Nitric to declare buckets within their application.
+**Developers** use Nitric to define required buckets within their application.
 
 - App code uses the [Bucket resource](/storage) from the Nitric SDK.
-- Developers configure buckets and implement application logic to securely access and manipulate bucket data.
-- Developers request the level of access they require for the bucket in their application logic e.g. read, write, delete.
-- Developers can implement handlers for on events such as read, write or delete.
+- Developers define buckets their application requires and implement logic to securely store/retrieve/delete files.
+- Developers _request_ the level of access they require for the bucket in their application logic e.g. read, write, delete.
+- Developers can implement handlers for file change events such as write or delete.
 
-**Operations** use default or overridden Terraform modules to provision the necessary resources for their target cloud.
+**Operations** use default or overridden IaC (e.g Terraform modules) to provision the necessary resources for their target cloud.
 
 <details>
   <summary>Example AWS Provider</summary>
 
 - **AWS S3** serves as the storage backend.
 - **AWS Lambda** functions are used to process events triggered by S3.
-- **AWS IAM** provides roles and policies for secure access to S3 buckets and Lambda functions, enforcing least priviledge access based on the developers request.
+- **AWS IAM** provides roles and policies for secure access to S3 buckets and Lambda functions, enforcing least privilege access based on the developers request.
 
 ```mermaid
 flowchart TD
@@ -113,8 +113,8 @@ sequenceDiagram
 
 - Ensures storage buckets have unique names by appending a randomly generated identifier. This avoids naming conflicts and aligns with best practices for globally accessible cloud resources.
 - Supports the addition of metadata tags for resource identification, management, and tracking, enabling better governance.
-- Configures storage bucket notifications to trigger functions or message queues based on specified events (e.g., object creation, update, or deletion).
-- Implements least privilege access by dynamically assigning permissions to functions or services that interact with the storage bucket.
+- Configures storage bucket notifications to trigger functions or message queues based on specified events (e.g., object update or deletion).
+- Implements least privilege access by only assigning requested permissions to functions or services that interact with the storage bucket.
 - Uses templates or dynamic blocks to handle multiple notification targets, allowing scalability and flexibility for different workflows.
 
 ## 4. Code

docs/architecture/keyvalue.mdx

@@ -6,12 +6,12 @@ description: 'Nitric Key/Value Store'
 
 ## 1. System Context
 
-**Developers** use Nitric to declare key/value stores within their application.
+**Developers** use Nitric to define required key/value stores within their application.
 
 - App code uses the [Key/Value resource](/keyvalue) from the Nitric SDK.
-- Developers configure key/value stores and implement application logic to securely access and manipulate data.
+- Developers define key/value stores their application requires and implement logic to securely read/write/delete values with unique keys.
 
-**Operations** use default or overridden Terraform modules to provision the necessary resources for their target cloud.
+**Operations** use default or overridden IaC (e.g Terraform modules) to provision the necessary resources for their target cloud.
 
 <details>
   <summary>Example AWS Provider</summary>

docs/architecture/queues.mdx

@@ -6,12 +6,12 @@ description: 'Nitric Queue'
 
 ## 1. System Context
 
-**Developers** use Nitric to declare message queues within their application.
+**Developers** use Nitric to define required message queues within their application.
 
 - App code uses the [Queue resource](/messaging#queues) from the Nitric SDK.
-- Developers configure queues and implement application logic to send and receive messages.
+- Developers define queues their application requires and implement application logic to send or receive messages.
 
-**Operations** use default or overridden Terraform modules to provision the necessary resources for their target cloud.
+**Operations** use default or overridden IaC (e.g Terraform modules) to provision the necessary resources for their target cloud.
 
 <details>
   <summary>Example AWS Provider</summary>

docs/architecture/schedules.mdx

@@ -6,7 +6,7 @@ description: 'Nitric Schedule'
 
 ## 1. System Context
 
-**Developers** use Nitric to declare scheduled tasks within their application.
+**Developers** use Nitric to defined scheduled tasks within their application.
 
 - App code uses the [Schedule resource](/schedules) from the Nitric SDK.
 - Developers configure the schedule with CRON or rate expressions like '7 days' and implement application logic to be executed when triggered.

docs/architecture/secrets.mdx

@@ -6,12 +6,12 @@ description: 'Nitric Secret'
 
 ## 1. System Context
 
-**Developers** use Nitric to declare secrets within their application.
+**Developers** use Nitric to define required secrets within their application.
 
 - App code uses the [Secrets resource](/secrets) from the Nitric SDK.
-- Developers configure secrets and implement application logic to securely access and manage these secrets.
+- Developers define secrets their application requires and implement logic to securely access and/or update secret values.
 
-**Operations** use default or overridden Terraform modules to provision the necessary resources for their target cloud.
+**Operations** use default or overridden IaC (e.g Terraform modules) to provision the necessary resources for their target cloud.
 
 <details>
   <summary>Example AWS Provider</summary>

docs/architecture/services.mdx

@@ -6,12 +6,12 @@ description: 'Service Deployment'
 
 ## 1. System Context
 
-**Developers** use Nitric to deploy services or functions within their application.
+**Developers** use Nitric to create services or functions within their application.
 
 - Application code is written in files that matches the pattern(s) in the nitric.yaml config file.
 - The **Nitric CLI** builds container images for their Lambda functions and push them to a container registry.
 
-**Operations** use default or overridden Terraform modules to provision the necessary resources for their target cloud.
+**Operations** use default or overridden IaC (e.g Terraform modules) to provision the necessary resources for their target cloud.
 
 <details>
   <summary>Example AWS Provider</summary>

docs/architecture/sql.mdx

@@ -6,7 +6,7 @@ description: 'Nitric SQL'
 
 ## 1. System Context
 
-**Developers** use Nitric to declare databases within their application (e.g., referencing a Postgres or MySQL database).
+**Developers** use Nitric to define required databases within their application (e.g., referencing a Postgres or MySQL database).
 
 - App code uses the [SQL database resources](/sql) from the Nitric SDK.
 - Developers can use any language specific client or ORM to interact with the databases.

docs/architecture/topics.mdx

@@ -6,12 +6,12 @@ description: 'Nitric Topic'
 
 ## 1. System Context
 
-**Developers** use Nitric to declare topics to enable event-driven communication within their application.
+**Developers** use Nitric to define required topics to enable event-driven communication within their application.
 
 - App code interacts with the [Topic resource](/messaging#topics) through defined topics and subscriptions.
-- Developers configure topics and implement application logic to publish and consume messages.
+- Developers define topics their application requires and implement application logic to publish or subscribe to messages.
 
-**Operations** use default or overridden Terraform modules to provision the necessary resources for their target cloud.
+**Operations** use default or overridden IaC (e.g Terraform modules) to provision the necessary resources for their target cloud.
 
 <details>
   <summary>Example AWS Provider</summary>

docs/architecture/websockets.mdx

@@ -6,12 +6,12 @@ description: 'Nitric WebSocket API'
 
 ## 1. System Context
 
-**Developers** use Nitric to declare WebSocket APIs within their application.
+**Developers** use Nitric to define required WebSocket APIs within their application.
 
 - App code interacts with the [WebSocket resource](/websocket) through defined routes and integrations.
 - Developers implement backend logic to handle WebSocket connections, messages, and disconnections.
 
-**Operations** use default or overridden Terraform modules to provision the necessary resources for their target cloud.
+**Operations** use default or overridden IaC (e.g Terraform modules) to provision the necessary resources for their target cloud.
 
 <details>
   <summary>Example AWS Provider</summary>