wip: feedback

nitrictech · Jan 24, 2025 · 766a1f5 · 766a1f5
1 parent 5cb12dc
commit 766a1f5
Show file tree

Hide file tree

Showing 25 changed files with 1,549 additions and 1,677 deletions.
diff --git a/dictionary.txt b/dictionary.txt
@@ -233,6 +233,9 @@ EC2
 .jpg
 .pdf
 preflight
+lifecycle
+NodeJS
+priviledge
 nav
 MacOS
 quantized

diff --git a/docs/architecture/apis.mdx b/docs/architecture/apis.mdx
@@ -0,0 +1,133 @@
+---
+description: 'Nitric API'
+---
+
+# APIS
+
+## 1. System Context
+
+**Developers** use Nitric to declare APIs and routes 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.
+
+**Operations** use default or overridden Terraform modules to provision the necessary resources for their target cloud.
+
+<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 ACM** manages TLS certificates for custom domain names.
+
+```mermaid
+flowchart TD
+    Developer["Developer"]
+    Operations["Operations"]
+    App["nitric up"]
+    APIGateway["AWS API Gateway v2<br>(HTTP API)"]
+    Lambda["AWS Lambda Functions"]
+    IAM["AWS IAM"]
+    ACM["AWS ACM<br>(Certificates)"]
+
+    Developer -->|Define API| App
+    Operations -->|Terraform| App
+    App -->|Create API Gateway| APIGateway
+    App -->|Deploy Lambda Functions| Lambda
+    App -->|Configure Permissions| IAM
+    APIGateway -->|Invoke| Lambda
+    ACM -->|Provide Certificates| APIGateway
+    IAM -->|Manage Access| APIGateway
+    App -->ACM
+
+classDef default line-height:1;
+classDef edgeLabel line-height:2;
+```
+
+</details>
+<details>
+  <summary>Example GCP Provider</summary>
+
+- **Google API Gateway** serves as the HTTP API management service, routing requests to backend services.
+- **Google Cloud Run** services are deployed to handle API requests with serverless execution.
+- **Google IAM** provides roles and policies to secure interactions between API Gateway, Cloud Run, and other GCP services.
+- **Certificates** (Google-managed or custom) ensure secure HTTPS communication for custom domain names.
+- **Google Service Account** is created and configured to allow API Gateway to invoke the Cloud Run backend securely.
+
+```mermaid
+flowchart TD
+    Developer["Developer"]
+    Operations["Operations"]
+    App["nitric up"]
+    APIGateway["Google API Gateway"]
+    CloudRun["Google Cloud Run"]
+    IAM["Google IAM"]
+    Certificates["Certificates<br>(Google Managed or Custom)"]
+    ServiceAccount["Google Service Account"]
+
+    Developer -->|Define API| App
+    Operations -->|Terraform| App
+    App -->|Create API Gateway| APIGateway
+    App -->|Deploy Cloud Run Services| CloudRun
+    App -->|Configure Permissions| IAM
+    APIGateway -->|Invoke| CloudRun
+    Certificates -->|Provide Certificates| APIGateway
+    IAM -->|Manage Access| APIGateway
+    App -->ServiceAccount
+    App -->Certificates
+
+classDef default line-height:1;
+classDef edgeLabel line-height:2;
+```
+
+</details>
+
+## 2. Sequence
+
+```mermaid
+sequenceDiagram
+    participant Client as Client
+    participant NitricSDK as Nitric SDK
+    participant NitricRuntime as Nitric Runtime
+    participant APIGateway as API Gateway
+    participant Worker as App Worker
+
+    Client->>NitricSDK: Send HTTP API request
+    NitricSDK->>NitricRuntime: Forward API request
+    NitricRuntime->>APIGateway: Register API routes (during deployment)
+
+    APIGateway->>NitricRuntime: Route incoming request
+    NitricRuntime->>Worker: Forward request to application logic
+    Worker-->>NitricRuntime: Process request and return response
+    NitricRuntime-->>APIGateway: Respond with result
+    APIGateway-->>Client: Return API response
+```
+
+## 3. Component
+
+### API Module
+
+- Dynamically creates and manages API gateways to expose application functionality through HTTP endpoints and routes.
+- Configures API properties, including protocol type, API specifications (e.g., OpenAPI), and metadata for identification and lifecycle management.
+- Provisions and associates backend integrations with API routes, supporting multiple targets such as serverless functions, containers, or application services.
+- Automates the setup of custom domain names with secure certificates, abstracting provider-specific configurations for HTTPS communication.
+- Grants least privilege permissions to enable secure communication between the API gateway and backend services, ensuring robust security practices.
+- Supports versioning and staging of APIs, enabling seamless updates and rollbacks without disrupting existing deployments.
+- Abstracts the complexities of cloud-native API gateway services, providing a unified interface for developing and deploying HTTP APIs across different providers.
+
+## 4. Code
+
+**Developers** write application code that uses the [API resource](/apis) from the SDK, configures the api and implement HTTP routes and middleware.
+
+SDK Reference by language -
+
+- [NodeJS SDK](/reference/nodejs/api/api)
+- [Python SDK](/reference/python/api/api)
+- [GO SDK](/reference/go/api/api)
+- [Dart SDK](/reference/dart/api/api)
+
+**Operations** will use or extend the Nitric Terraform reference modules:
+
+- [AWS API Terrform Module](https://github.com/nitrictech/nitric/blob/main/cloud/aws/deploytf/.nitric/modules/api/main.tf)
+- [GCP API Terrform Module](https://github.com/nitrictech/nitric/blob/main/cloud/gcp/deploytf/.nitric/modules/api/main.tf)
diff --git a/docs/architecture/buckets.mdx b/docs/architecture/buckets.mdx
@@ -0,0 +1,134 @@
+---
+description: 'C4 Buckets'
+---
+
+# Storage - Buckets
+
+## 1. System Context
+
+**Developers** use Nitric to declare 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.
+
+**Operations** use default or overridden 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.
+
+```mermaid
+flowchart TD
+    Developer["Developer"]
+    Operations["Operations"]
+    App["nitric up"]
+    S3Bucket["AWS S3 Bucket"]
+    Lambda["AWS Lambda Functions"]
+    IAM["AWS IAM"]
+
+    Developer -->|Code| App
+    Operations -->|Terraform| App
+    App -->|Create S3 Bucket| S3Bucket
+    App -->|Configure Notifications| S3Bucket
+    IAM -->|Allow Lambda Invocation| Lambda
+    Lambda -->|Store/Retrieve Data/Trigger onEvents| S3Bucket
+    App -->|Provide Access| IAM
+    IAM -->S3Bucket
+
+classDef default line-height:1;
+classDef edgeLabel line-height:2;
+```
+
+</details>
+<details>
+  <summary>Example GCP Provider</summary>
+
+- **Google Cloud Storage** serves as the storage backend.
+- **Google Cloud Pub/Sub** is used to publish events triggered by Cloud Storage notifications.
+- **Google IAM** provides roles and policies for secure access to Cloud Storage buckets and Pub/Sub topics, enforcing least privilege access based on the developer's request.
+
+```mermaid
+flowchart TD
+    Developer["Developer"]
+    Operations["Operations"]
+    App["nitric up"]
+    GCSBucket["Google Cloud Storage Bucket"]
+    PubSubTopic["Google Pub/Sub Topic"]
+    PubSubSubscription["Google Pub/Sub Subscription"]
+    IAM["Google IAM"]
+    Lambda["AWS Lambda Functions"]
+
+
+    Developer -->|Code| App
+    Operations -->|Terraform| App
+    App -->|Create Storage Bucket| GCSBucket
+    App -->|Configure Notifications| GCSBucket
+    IAM -->|Allow Pub/Sub Publishing| PubSubTopic
+    PubSubTopic -->|Publish Events| PubSubSubscription
+    PubSubSubscription -->|Deliver Notifications| Lambda
+    App -->|Provide Access| IAM
+    IAM -->GCSBucket
+    IAM -->PubSubTopic
+    Lambda -->|Store/Retrieve Data/Trigger onEvents| GCSBucket
+
+
+classDef default line-height:1;
+classDef edgeLabel line-height:2;
+```
+
+</details>
+
+## 2. Sequence
+
+```mermaid
+sequenceDiagram
+    participant Client as Client
+    participant NitricSDK as Nitric SDK
+    participant NitricRuntime as Nitric Runtime
+    participant CloudStorage as Cloud Storage (e.g., S3, GCS)
+
+    Client->>NitricSDK: Perform storage operation (e.g., write, read, delete)
+    NitricSDK->>NitricRuntime: Forward storage API call
+    NitricRuntime->>CloudStorage: Execute storage operation
+
+    alt Successful Operation
+        CloudStorage-->>NitricRuntime: Return result (e.g., data or success status)
+        NitricRuntime-->>NitricSDK: Return result
+        NitricSDK-->>Client: Return result to client
+    else Failure
+        CloudStorage-->>NitricRuntime: Return error
+        NitricRuntime-->>NitricSDK: Forward error
+        NitricSDK-->>Client: Return error response
+    end
+```
+
+## 3. Component
+
+### Bucket Module
+
+- 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.
+- Uses templates or dynamic blocks to handle multiple notification targets, allowing scalability and flexibility for different workflows.
+
+## 4. Code
+
+**Developers** write application code that uses the [Bucket resource](/storage) from the SDK, configures the bucket, and implements the application logic to read, write and delete files.
+
+SDK Reference by language -
+
+- [NodeJS SDK](/reference/nodejs/storage/bucket)
+- [Python SDK](/reference/python/storage/bucket)
+- [GO SDK](/reference/go/storage/bucket)
+- [Dart SDK](/reference/dart/storage/bucket)
+
+**Operations** will use or extend the Nitric Terraform reference modules:
+
+- [AWS Storage Bucket Terrform Module](https://github.com/nitrictech/nitric/blob/main/cloud/aws/deploytf/.nitric/modules/bucket/main.tf)
+- [GCP Storage Bucket Terrform Module](https://github.com/nitrictech/nitric/blob/main/cloud/gcp/deploytf/.nitric/modules/bucket/main.tf)