Skip to content
This repository was archived by the owner on May 20, 2025. It is now read-only.

Commit 75b69d5

Browse files
raksivraksiv
committed
wip: feedback
1 parent 5cb12dc commit 75b69d5

25 files changed

+1552
-1677
lines changed

‎dictionary.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,12 @@ EC2
233233
.jpg
234234
.pdf
235235
preflight
236+
lifecycle
237+
NodeJS
238+
priviledge
239+
APIS
240+
TLS
241+
SRE
236242
nav
237243
MacOS
238244
quantized

‎docs/architecture/apis.mdx‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
description: 'Nitric API'
3+
---
4+
5+
# APIS
6+
7+
## 1. System Context
8+
9+
**Developers** use Nitric to declare APIs and routes within their application.
10+
11+
- App code uses the [API resource](/apis) through defined endpoints.
12+
- Developers define API specifications and implement backend logic to handle HTTP requests.
13+
14+
**Operations** use default or overridden Terraform modules to provision the necessary resources for their target cloud.
15+
16+
<details>
17+
<summary>Example AWS Provider</summary>
18+
19+
- **AWS API Gateway v2** serves as the HTTP API management service.
20+
- **AWS Lambda** functions are deployed to handle API requests.
21+
- **AWS IAM** (implicitly assumed) provides roles and policies for secure interaction between API Gateway and Lambda functions.
22+
- **AWS ACM** manages TLS certificates for custom domain names.
23+
24+
```mermaid
25+
flowchart TD
26+
Developer["Developer"]
27+
Operations["Operations"]
28+
App["nitric up"]
29+
APIGateway["AWS API Gateway v2<br>(HTTP API)"]
30+
Lambda["AWS Lambda Functions"]
31+
IAM["AWS IAM"]
32+
ACM["AWS ACM<br>(Certificates)"]
33+
34+
Developer -->|Define API| App
35+
Operations -->|Terraform| App
36+
App -->|Create API Gateway| APIGateway
37+
App -->|Deploy Lambda Functions| Lambda
38+
App -->|Configure Permissions| IAM
39+
APIGateway -->|Invoke| Lambda
40+
ACM -->|Provide Certificates| APIGateway
41+
IAM -->|Manage Access| APIGateway
42+
App -->ACM
43+
44+
classDef default line-height:1;
45+
classDef edgeLabel line-height:2;
46+
```
47+
48+
</details>
49+
<details>
50+
<summary>Example GCP Provider</summary>
51+
52+
- **Google API Gateway** serves as the HTTP API management service, routing requests to backend services.
53+
- **Google Cloud Run** services are deployed to handle API requests with serverless execution.
54+
- **Google IAM** provides roles and policies to secure interactions between API Gateway, Cloud Run, and other GCP services.
55+
- **Certificates** (Google-managed or custom) ensure secure HTTPS communication for custom domain names.
56+
- **Google Service Account** is created and configured to allow API Gateway to invoke the Cloud Run backend securely.
57+
58+
```mermaid
59+
flowchart TD
60+
Developer["Developer"]
61+
Operations["Operations"]
62+
App["nitric up"]
63+
APIGateway["Google API Gateway"]
64+
CloudRun["Google Cloud Run"]
65+
IAM["Google IAM"]
66+
Certificates["Certificates<br>(Google Managed or Custom)"]
67+
ServiceAccount["Google Service Account"]
68+
69+
Developer -->|Define API| App
70+
Operations -->|Terraform| App
71+
App -->|Create API Gateway| APIGateway
72+
App -->|Deploy Cloud Run Services| CloudRun
73+
App -->|Configure Permissions| IAM
74+
APIGateway -->|Invoke| CloudRun
75+
Certificates -->|Provide Certificates| APIGateway
76+
IAM -->|Manage Access| APIGateway
77+
App -->ServiceAccount
78+
App -->Certificates
79+
80+
classDef default line-height:1;
81+
classDef edgeLabel line-height:2;
82+
```
83+
84+
</details>
85+
86+
## 2. Sequence
87+
88+
```mermaid
89+
sequenceDiagram
90+
participant Client as Client
91+
participant NitricSDK as Nitric SDK
92+
participant NitricRuntime as Nitric Runtime
93+
participant APIGateway as API Gateway
94+
participant Worker as App Worker
95+
96+
Client->>NitricSDK: Send HTTP API request
97+
NitricSDK->>NitricRuntime: Forward API request
98+
NitricRuntime->>APIGateway: Register API routes (during deployment)
99+
100+
APIGateway->>NitricRuntime: Route incoming request
101+
NitricRuntime->>Worker: Forward request to application logic
102+
Worker-->>NitricRuntime: Process request and return response
103+
NitricRuntime-->>APIGateway: Respond with result
104+
APIGateway-->>Client: Return API response
105+
```
106+
107+
## 3. Component
108+
109+
### API Module
110+
111+
- Dynamically creates and manages API gateways to expose application functionality through HTTP endpoints and routes.
112+
- Configures API properties, including protocol type, API specifications (e.g., OpenAPI), and metadata for identification and lifecycle management.
113+
- Provisions and associates backend integrations with API routes, supporting multiple targets such as serverless functions, containers, or application services.
114+
- Automates the setup of custom domain names with secure certificates, abstracting provider-specific configurations for HTTPS communication.
115+
- Grants least privilege permissions to enable secure communication between the API gateway and backend services, ensuring robust security practices.
116+
- Supports versioning and staging of APIs, enabling seamless updates and rollbacks without disrupting existing deployments.
117+
- Abstracts the complexities of cloud-native API gateway services, providing a unified interface for developing and deploying HTTP APIs across different providers.
118+
119+
## 4. Code
120+
121+
**Developers** write application code that uses the [API resource](/apis) from the SDK, configures the api and implement HTTP routes and middleware.
122+
123+
SDK Reference by language -
124+
125+
- [NodeJS SDK](/reference/nodejs/api/api)
126+
- [Python SDK](/reference/python/api/api)
127+
- [GO SDK](/reference/go/api/api)
128+
- [Dart SDK](/reference/dart/api/api)
129+
130+
**Operations** will use or extend the Nitric Terraform reference modules:
131+
132+
- [AWS API Terrform Module](https://github.com/nitrictech/nitric/blob/main/cloud/aws/deploytf/.nitric/modules/api/main.tf)
133+
- [GCP API Terrform Module](https://github.com/nitrictech/nitric/blob/main/cloud/gcp/deploytf/.nitric/modules/api/main.tf)

‎docs/architecture/buckets.mdx‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
description: 'C4 Buckets'
3+
---
4+
5+
# Storage - Buckets
6+
7+
## 1. System Context
8+
9+
**Developers** use Nitric to declare buckets within their application.
10+
11+
- App code uses the [Bucket resource](/storage) from the Nitric SDK.
12+
- Developers configure buckets and implement application logic to securely access and manipulate bucket data.
13+
- Developers request the level of access they require for the bucket in their application logic e.g. read, write, delete.
14+
- Developers can implement handlers for on events such as read, write or delete.
15+
16+
**Operations** use default or overridden Terraform modules to provision the necessary resources for their target cloud.
17+
18+
<details>
19+
<summary>Example AWS Provider</summary>
20+
21+
- **AWS S3** serves as the storage backend.
22+
- **AWS Lambda** functions are used to process events triggered by S3.
23+
- **AWS IAM** provides roles and policies for secure access to S3 buckets and Lambda functions, enforcing least priviledge access based on the developers request.
24+
25+
```mermaid
26+
flowchart TD
27+
Developer["Developer"]
28+
Operations["Operations"]
29+
App["nitric up"]
30+
S3Bucket["AWS S3 Bucket"]
31+
Lambda["AWS Lambda Functions"]
32+
IAM["AWS IAM"]
33+
34+
Developer -->|Code| App
35+
Operations -->|Terraform| App
36+
App -->|Create S3 Bucket| S3Bucket
37+
App -->|Configure Notifications| S3Bucket
38+
IAM -->|Allow Lambda Invocation| Lambda
39+
Lambda -->|Store/Retrieve Data/Trigger onEvents| S3Bucket
40+
App -->|Provide Access| IAM
41+
IAM -->S3Bucket
42+
43+
classDef default line-height:1;
44+
classDef edgeLabel line-height:2;
45+
```
46+
47+
</details>
48+
<details>
49+
<summary>Example GCP Provider</summary>
50+
51+
- **Google Cloud Storage** serves as the storage backend.
52+
- **Google Cloud Pub/Sub** is used to publish events triggered by Cloud Storage notifications.
53+
- **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.
54+
55+
```mermaid
56+
flowchart TD
57+
Developer["Developer"]
58+
Operations["Operations"]
59+
App["nitric up"]
60+
GCSBucket["Google Cloud Storage Bucket"]
61+
PubSubTopic["Google Pub/Sub Topic"]
62+
PubSubSubscription["Google Pub/Sub Subscription"]
63+
IAM["Google IAM"]
64+
Lambda["AWS Lambda Functions"]
65+
66+
67+
Developer -->|Code| App
68+
Operations -->|Terraform| App
69+
App -->|Create Storage Bucket| GCSBucket
70+
App -->|Configure Notifications| GCSBucket
71+
IAM -->|Allow Pub/Sub Publishing| PubSubTopic
72+
PubSubTopic -->|Publish Events| PubSubSubscription
73+
PubSubSubscription -->|Deliver Notifications| Lambda
74+
App -->|Provide Access| IAM
75+
IAM -->GCSBucket
76+
IAM -->PubSubTopic
77+
Lambda -->|Store/Retrieve Data/Trigger onEvents| GCSBucket
78+
79+
80+
classDef default line-height:1;
81+
classDef edgeLabel line-height:2;
82+
```
83+
84+
</details>
85+
86+
## 2. Sequence
87+
88+
```mermaid
89+
sequenceDiagram
90+
participant Client as Client
91+
participant NitricSDK as Nitric SDK
92+
participant NitricRuntime as Nitric Runtime
93+
participant CloudStorage as Cloud Storage (e.g., S3, GCS)
94+
95+
Client->>NitricSDK: Perform storage operation (e.g., write, read, delete)
96+
NitricSDK->>NitricRuntime: Forward storage API call
97+
NitricRuntime->>CloudStorage: Execute storage operation
98+
99+
alt Successful Operation
100+
CloudStorage-->>NitricRuntime: Return result (e.g., data or success status)
101+
NitricRuntime-->>NitricSDK: Return result
102+
NitricSDK-->>Client: Return result to client
103+
else Failure
104+
CloudStorage-->>NitricRuntime: Return error
105+
NitricRuntime-->>NitricSDK: Forward error
106+
NitricSDK-->>Client: Return error response
107+
end
108+
```
109+
110+
## 3. Component
111+
112+
### Bucket Module
113+
114+
- 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.
115+
- Supports the addition of metadata tags for resource identification, management, and tracking, enabling better governance.
116+
- Configures storage bucket notifications to trigger functions or message queues based on specified events (e.g., object creation, update, or deletion).
117+
- Implements least privilege access by dynamically assigning permissions to functions or services that interact with the storage bucket.
118+
- Uses templates or dynamic blocks to handle multiple notification targets, allowing scalability and flexibility for different workflows.
119+
120+
## 4. Code
121+
122+
**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.
123+
124+
SDK Reference by language -
125+
126+
- [NodeJS SDK](/reference/nodejs/storage/bucket)
127+
- [Python SDK](/reference/python/storage/bucket)
128+
- [GO SDK](/reference/go/storage/bucket)
129+
- [Dart SDK](/reference/dart/storage/bucket)
130+
131+
**Operations** will use or extend the Nitric Terraform reference modules:
132+
133+
- [AWS Storage Bucket Terrform Module](https://github.com/nitrictech/nitric/blob/main/cloud/aws/deploytf/.nitric/modules/bucket/main.tf)
134+
- [GCP Storage Bucket Terrform Module](https://github.com/nitrictech/nitric/blob/main/cloud/gcp/deploytf/.nitric/modules/bucket/main.tf)

0 commit comments

Comments
 (0)