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

Commit 5cb12dc

Browse files
raksivraksiv
committed
wip: experimenting with c4 diagrams
1 parent bafa7a6 commit 5cb12dc

12 files changed

+1688
-0
lines changed

‎docs/guides/c4/c4-api.mdx‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
description: 'C4 Api'
3+
tags:
4+
- C4
5+
published_at: 2024-07-25
6+
---
7+
8+
# Nitric 'API' Architecture
9+
10+
## 1. System Context (Level 1)
11+
12+
- A **Developer** uses Nitric to create and manage APIs within their application.
13+
- App code interacts with the **API resource** through defined endpoints.
14+
- Developers define API specifications and implement backend logic to handle requests.
15+
- **Operations** use default or overridden Terraform modules to provision the necessary AWS API Gateway resources.
16+
- **AWS API Gateway v2** serves as the HTTP API management service.
17+
- **AWS Lambda** functions are deployed to handle API requests.
18+
- **AWS IAM** (implicitly assumed) provides roles and policies for secure interaction between API Gateway and Lambda functions.
19+
- **AWS ACM** manages SSL/TLS certificates for custom domain names.
20+
21+
```mermaid
22+
flowchart TD
23+
Developer["Developer"]
24+
Operations["Operations"]
25+
App["nitric up"]
26+
APIGateway["AWS API Gateway v2<br>(HTTP API)"]
27+
Lambda["AWS Lambda Functions"]
28+
IAM["AWS IAM"]
29+
ACM["AWS ACM<br>(Certificates)"]
30+
31+
Developer -->|Define API| App
32+
Operations -->|Terraform| App
33+
App -->|Create API Gateway| APIGateway
34+
App -->|Deploy Lambda Functions| Lambda
35+
App -->|Configure Permissions| IAM
36+
APIGateway -->|Invoke| Lambda
37+
ACM -->|Provide Certificates| APIGateway
38+
IAM -->|Manage Access| APIGateway
39+
App -->ACM
40+
41+
classDef default line-height:1;
42+
classDef edgeLabel line-height:2;
43+
```
44+
45+
## 2. Container (Level 2)
46+
47+
Each **API** is managed through AWS API Gateway v2 and interacts with backend Lambda functions to process HTTP requests.
48+
49+
```mermaid
50+
flowchart TD
51+
Nitric["Nitric Application"]
52+
Nitric -->B(API 1)
53+
Nitric -->C(API 2)
54+
Nitric -->D(...)
55+
B(API 1) -->E(HTTP GET)
56+
B(API 1) -->F(HTTP POST)
57+
B(API 1) -->G(...)
58+
59+
classDef default line-height:1;
60+
classDef edgeLabel line-height:2;
61+
```
62+
63+
## 3. Component (Level 3)
64+
65+
### API Module
66+
67+
- **aws_apigatewayv2_api.api_gateway**
68+
- Creates an AWS API Gateway v2 HTTP API.
69+
- Configures the API name, protocol type, API specification (`body`), and tags for identification and management.
70+
- **aws_apigatewayv2_stage.stage**
71+
- Creates a stage for the API Gateway.
72+
- Sets the stage name to `$default` and enables automatic deployment of changes.
73+
- **aws_lambda_permission.apigw_lambda**
74+
- Grants API Gateway permission to invoke the specified Lambda functions.
75+
- Iterates over `var.target_lambda_functions` to set permissions for each target function.
76+
- **data.aws_acm_certificate.cert**
77+
- Looks up existing ACM certificates for the specified domains.
78+
- Iterates over `var.domains` to retrieve certificate details for each domain.
79+
- **aws_apigatewayv2_domain_name.domain**
80+
81+
- Creates custom domain names for the API Gateway using the retrieved ACM certificates.
82+
- Configures domain name settings, including the certificate ARN, endpoint type, and security policy.
83+
84+
## 4. Code (Level 4)
85+
86+
**Developers** write application code that imports the 'api' resource from the SDK, configures the api, and implements HTTP routes, implement middleware, etc.
87+
88+
```typescript
89+
import { api } from '@nitric/sdk'
90+
91+
const publicApi = api('public')
92+
93+
api('public').get('/customers', (ctx) => {
94+
// construct response for the GET: /customers request...
95+
const responseBody = {}
96+
ctx.res.json(responseBody)
97+
})
98+
99+
const authMiddleware = async (ctx, next) => {
100+
// Perform auth validation.
101+
return await next(ctx)
102+
}
103+
104+
const privateApi = api('private', { middleware: authMiddleware })
105+
```
106+
107+
**Operations** will use the provided Terraform module to create and manage the AWS API Gateway as defined.
108+
109+
```hcl
110+
resource "aws_apigatewayv2_api" "api_gateway" {
111+
name = var.name
112+
protocol_type = "HTTP"
113+
body = var.spec
114+
tags = {
115+
"x-nitric-${var.stack_id}-name" = var.name,
116+
"x-nitric-${var.stack_id}-type" = "api",
117+
}
118+
}
119+
120+
resource "aws_apigatewayv2_stage" "stage" {
121+
api_id = aws_apigatewayv2_api.api_gateway.id
122+
name = "$default"
123+
auto_deploy = true
124+
}
125+
126+
# deploy lambda permissions for execution
127+
resource "aws_lambda_permission" "apigw_lambda" {
128+
for_each = var.target_lambda_functions
129+
action = "lambda:InvokeFunction"
130+
function_name = each.value
131+
principal = "apigateway.amazonaws.com"
132+
source_arn = "${aws_apigatewayv2_api.api_gateway.execution_arn}/*/*/*"
133+
}
134+
135+
# look up existing certificate for domains
136+
data "aws_acm_certificate" "cert" {
137+
for_each = var.domains
138+
domain = each.value
139+
}
140+
141+
# deploy custom domain names
142+
resource "aws_apigatewayv2_domain_name" "domain" {
143+
for_each = var.domains
144+
domain_name = each.value
145+
domain_name_configuration {
146+
certificate_arn = data.aws_acm_certificate.cert[each.key].arn
147+
endpoint_type = "REGIONAL"
148+
security_policy = "TLS_1_2"
149+
}
150+
}
151+
```

‎docs/guides/c4/c4-big-picture.mdx‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
description: 'C4 Nitric High-Level Architecture'
3+
tags:
4+
- C4
5+
published_at: 2024-07-25
6+
---
7+
8+
# Nitric High-Level Architecture
9+
10+
Nitric allows your team to work together to build an application:
11+
12+
- **Developer**: Writes application code with built-in support for APIs, file storage (bucket), secrets, key‑value store, and RDS, leveraging the Nitric SDK.
13+
- **Operations**: Customize, extend or use Nitric's generated IaC (Terraform or Pulumi) to provision and manage the resources that the developer needs for their application.
14+
- **SRE**: Configure environment/region/policy specific details, they also are heavily involved in overseeing that the Terraform modules themselves adhere to governance standards.
15+
16+
The roles above may overlap depending on your organization structure, for example, it is not abnormal Developers to assume all roles, or for Operations and SRE responsibilities to be handled by the same team.
17+
18+
```mermaid
19+
flowchart TD
20+
Developer[Developer]
21+
Operations[Operations]
22+
SRE[Site Reliablility Engineer]
23+
App[Nitric App - 'nitric up']
24+
Repo[Code Repository]
25+
26+
API[API Gateway]
27+
Bucket[Bucket - AWS S3]
28+
Secrets[Secrets - AWS Secrets Manager\n]
29+
KVStore[Key-Value Store - AWS DynamoDB]
30+
RDS[Relational Database - AWS RDS/Aurora]
31+
Other[Other resources]
32+
33+
SRE -->|Deployment Config| Repo
34+
Developer -->|Code| Repo
35+
Operations -->|Extend/Customize Terraform| Repo
36+
Repo-->App
37+
38+
App -->|Exposes REST/HTTP Routes| API
39+
App -->|Stores/Retrieves Files| Bucket
40+
App -->|Manages Sensitive Data| Secrets
41+
App -->|Reads/Writes Data| KVStore
42+
App -->|Executes SQL Queries| RDS
43+
App -->|1..n|Other
44+
45+
classDef default line-height:1;
46+
classDef edgeLabel line-height:2;
47+
```
48+
49+
Nitric applications can have any number of APIs, Secrets, Buckets etc. Providers can also be extended to further support new resources, many which will work across all cloud providers and some that are cloud specific.
50+
51+
## Example: Handling HTTP requests.
52+
53+
Interaction with services that have been exposed as HTTP routes within an API gateway, Scheduled tasks, Event subscriptions, WebSocket handlers and more.
54+
55+
```mermaid
56+
flowchart TD
57+
%% Actors
58+
Browser[Client Browser]
59+
60+
%% Nitric Application Containers
61+
API[HTTP API - API Gateway]
62+
Service[GET Route]
63+
Service2[POST Route]
64+
Service3[...]
65+
66+
%% Backend Services / Resources
67+
Bucket[AWS S3 Bucket]
68+
Secrets[AWS Secrets Manager]
69+
KVStore[AWS DynamoDB - Key-Value Store]
70+
RDS[AWS RDS/Aurora]
71+
72+
%% Interactions
73+
Browser -->|Sends HTTP Request| API
74+
API -->|Triggers Service| Service
75+
API -->|Triggers Service| Service2
76+
API -->|Triggers Service| Service3
77+
Service -->|Manage/Uploads/Downloads files| Bucket
78+
Service -->|Retrieves credentials/config data| Secrets
79+
Service -->|Reads/Writes key data| KVStore
80+
Service -->|Queries/Updates relational data| RDS
81+
82+
classDef default line-height:1;
83+
classDef edgeLabel line-height:2;
84+
```
85+
86+
- The **Client Browser** sends an HTTP request to the **API Gateway**.
87+
- The **API Gateway** acts as a proxy, forwarding the request to the appropriate **Services**.
88+
- The **Services** process the request by coordinating with different backend services, this is done through :
89+
- They interact with one or more **AWS S3 Bucket** to manage files.
90+
- They retrieve credentials or configuration from **AWS Secrets Manager**.
91+
- They use **AWS DynamoDB** for fast key-value operations.
92+
- They query or update structured data in **AWS RDS/Aurora**.

‎docs/guides/c4/c4-buckets.mdx‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
description: 'C4 Buckets'
3+
tags:
4+
- C4
5+
published_at: 2024-07-25
6+
---
7+
8+
# Nitric 'Bucket' Architecture
9+
10+
## 1. System Context (Level 1)
11+
12+
- A **Developer** uses Nitric to manage S3 buckets within their application.
13+
- App code imports the **Bucket resource** from the Nitric SDK.
14+
- Developers configure buckets and implement application logic to securely access and manipulate bucket data.
15+
- Developers can also implement hanlders for on events like on read, write or delete.
16+
- **Operations** use default or overridden Terraform modules to provision the necessary AWS S3 resources.
17+
- **AWS S3** serves as the storage backend.
18+
- **AWS Lambda** functions are used to process events triggered by S3.
19+
- **AWS IAM** provides roles and policies for secure access to S3 buckets and Lambda functions.
20+
- **Random ID** resource is used to generate unique bucket names.
21+
22+
```mermaid
23+
flowchart TD
24+
Developer["Developer"]
25+
Operations["Operations"]
26+
App["nitric up"]
27+
S3Bucket["AWS S3 Bucket"]
28+
Lambda["AWS Lambda Functions"]
29+
IAM["AWS IAM"]
30+
31+
Developer -->|Code| App
32+
Operations -->|Terraform| App
33+
App -->|Create S3 Bucket| S3Bucket
34+
App -->|Configure Notifications| S3Bucket
35+
App -->|Allow Lambda Invocation| Lambda
36+
S3Bucket -->|Store/Retrieve Data| App
37+
Lambda -->|Process Events| App
38+
App -->|Provide Access| IAM
39+
IAM -->S3Bucket
40+
41+
classDef default line-height:1;
42+
classDef edgeLabel line-height:2;
43+
```
44+
45+
## 2. Container (Level 2)
46+
47+
Each **Bucket** is managed through AWS S3 and accessed by the application through securely configured mechanisms provided by Nitric.
48+
49+
```mermaid
50+
flowchart TD
51+
Nitric["Nitric Application"]
52+
Nitric -->B(Bucket 1)
53+
Nitric -->C(Bucket 2)
54+
Nitric -->D(...)
55+
B(BUCKET 1) -->E(ON Read)
56+
B(BUCKET 1) -->F(ON Write)
57+
B(BUCKET 1) -->G(ON Delete)
58+
```
59+
60+
## 3. Component (Level 3)
61+
62+
### Bucket Module
63+
64+
- **random_id.bucket_id**
65+
- Generates a random ID for the S3 bucket to ensure unique naming.
66+
- **aws_s3_bucket.bucket**
67+
- Creates an AWS S3 bucket with a unique name by appending the generated random ID.
68+
- Configures tags for identification and management.
69+
- **aws_lambda_permission.allow_bucket**
70+
- Grants AWS S3 permission to invoke the specified Lambda functions.
71+
- Iterates over `var.notification_targets` to set permissions for each target.
72+
- **aws_s3_bucket_notification.bucket_notification**
73+
- Configures S3 bucket notifications to trigger Lambda functions based on specified events.
74+
- Uses dynamic blocks to handle multiple Lambda function notifications.
75+
76+
## 4. Code (Level 4)
77+
78+
**Developers** write application code that imports the 'bucket' resource from the SDK, configures the bucket, and implements the application logic to read, write and delete files.
79+
80+
```typescript
81+
import { bucket } from '@nitric/sdk'
82+
83+
const profiles = bucket('profiles').allow('read')
84+
85+
const image = await profiles.file('users/bruce-wayne/profile.png').read()
86+
```
87+
88+
**Operations** will use the provided Terraform module to create and manage the AWS S3 Buckets as defined.
89+
90+
```hcl
91+
92+
# Generate a random id for the bucket
93+
resource "random_id" "bucket_id" {
94+
byte_length = 8
95+
96+
keepers = {
97+
# Generate a new id each time we switch to a new AMI id
98+
bucket_name = var.bucket_name
99+
}
100+
}
101+
102+
# AWS S3 bucket
103+
resource "aws_s3_bucket" "bucket" {
104+
bucket = "${var.bucket_name}-${random_id.bucket_id.hex}"
105+
106+
tags = {
107+
"x-nitric-${var.stack_id}-name" = var.bucket_name
108+
"x-nitric-${var.stack_id}-type" = "bucket"
109+
}
110+
}
111+
112+
# Deploy bucket lambda invocation permissions
113+
resource "aws_lambda_permission" "allow_bucket" {
114+
for_each = var.notification_targets
115+
action = "lambda:InvokeFunction"
116+
function_name = each.value.arn
117+
principal = "s3.amazonaws.com"
118+
source_arn = aws_s3_bucket.bucket.arn
119+
}
120+
121+
# Deploy lambda notifications
122+
resource "aws_s3_bucket_notification" "bucket_notification" {
123+
bucket = aws_s3_bucket.bucket.id
124+
125+
// make dynamic blocks for lambda function
126+
dynamic "lambda_function" {
127+
for_each = var.notification_targets
128+
content {
129+
lambda_function_arn = lambda_function.value.arn
130+
events = lambda_function.value.events
131+
filter_prefix = lambda_function.value.prefix
132+
}
133+
}
134+
}
135+
```

0 commit comments

Comments
 (0)