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

Commit f26de9a

Browse files
jyecuschjyecusch
committed
update architecture over page
1 parent fc17725 commit f26de9a

File tree

1 file changed

+89
-86
lines changed

1 file changed

+89
-86
lines changed

‎docs/architecture/index.mdx‎

Lines changed: 89 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,31 @@ description: "Learn about Nitric's architecture and how developers, operations t
66

77
Nitric allows your team to work together to build an application:
88

9-
- **Developer**: Writes application code with built-in support for APIs, file storage (bucket), secrets, key/value store, and RDS, leveraging the Nitric SDK.
10-
- **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.
11-
- **SRE**: Configure environment/region/policy specific details, they also are heavily involved in overseeing that the Terraform modules themselves adhere to governance standards.
12-
- **Nitric**: Automatically generates a specification for resource declarations and fulfills them by orchestrating a cloud deployment using IaC modules and container images tailored to the runtime requirements of the application code. While many examples focus on AWS as the target cloud, Nitric's flexibility allows providers to support any cloud environment or even multiple clouds simultaneously.
9+
- **Developers**: Writes application code with built-in support for APIs, storage (bucket), secrets, key/value store, SQL databases and other cloud resources, leveraging the Nitric SDK.
10+
- **Automation Engineers**: Customize, extend or use Nitric's generated IaC (Terraform or Pulumi) to provision and manage the resources needed to support applications.
11+
- **Operations**: Configure environment/region/policy specific details, they also are heavily involved in overseeing that the Terraform, Pulumi or other IaC modules adhere to governance standards.
1312

14-
The roles above may overlap depending on your organization structure, for example, it is not abnormal for Developers to assume all roles, or for Operations and SRE responsibilities to be handled by the same team.
13+
<Note>
14+
These roles are only representative, they often overlap or further divide
15+
depending on team structure. For example, it's not unusual in smaller teams
16+
for Developers to assume all roles, or for Automation and Operations to be
17+
handled by the same team.
18+
</Note>
19+
20+
**Nitric** interacts with code to generate a specification of the resources required by each application. It then uses one or more IaC/cloud-specific plugins to turn those requirements into Infrastructure-as-Code (e.g. Terraform) or fully automate cloud deployments, which fully satisfy all of the applications infrastructure requirements. Effectively, Nitric is a cloud-agnostic way to define and deploy cloud applications, which automates the transition from code to cloud resources.
21+
22+
While many Nitric examples focus on AWS, Nitric's flexibility allows plugins (providers) to support any cloud or on-prem environment, even multiple clouds simultaneously if that's required.
1523

1624
```mermaid
1725
flowchart TD
1826
Developer[Developer]
27+
Automation[Automation Engineer]
1928
Operations[Operations]
20-
SRE[Site Reliablility Engineer]
2129
App[Deployed Application]
2230
CLI[Nitric CLI - 'nitric up']
2331
Provider[Nitric Provider]
2432
Container[Container Images]
33+
NitricSpec[Nitric Specification]
2534
2635
API[API Gateway]
2736
Bucket[Bucket]
@@ -30,13 +39,14 @@ flowchart TD
3039
RDS[Relational Database]
3140
Other[Other Resources]
3241
33-
SRE -->|Deployment Config| CLI
42+
Operations -->|Deployment Config| CLI
3443
Developer -->|Code| CLI
35-
Operations -->|Extend/Customize IaC Modules| Provider
36-
CLI -->|Resource Specification| Provider
44+
Automation -->|Extend/Customize IaC Modules| Provider
45+
CLI -->|Generate| NitricSpec
3746
CLI -->|Build| Container
3847
Provider -->App
3948
Container -->Provider
49+
NitricSpec -->Provider
4050
4151
App -->|Exposes REST/HTTP Routes| API
4252
App -->|Stores/Retrieves Files| Bucket
@@ -77,10 +87,10 @@ flowchart TD
7787
API -->|Triggers Service| Service
7888
API -->|Triggers Service| Service2
7989
API -->Service3
80-
Service -->|Manage/Uploads/Downloads files| Bucket
81-
Service -->|Retrieves credentials/config data| Secrets
82-
Service -->|Reads/Writes key data| KVStore
83-
Service -->|Queries/Updates relational data| RDS
90+
Service -->|Read/Write| Bucket
91+
Service -->|Access| Secrets
92+
Service -->|Read/Write| KVStore
93+
Service -->|Execute Queries| RDS
8494
8595
classDef default line-height:1;
8696
classDef edgeLabel line-height:2;
@@ -99,133 +109,126 @@ flowchart TD
99109
100110
%% Nitric Application Containers (WebSocket Handlers)
101111
WS[WebSocket API]
102-
Conn[onConnection Handler]
103-
Msg[onMessage Handler]
104-
Disc[onDisconnect Handler]
112+
Conn[onConnection Callback]
113+
Msg[onMessage Callback]
114+
Disc[onDisconnect Callback]
105115
106116
%% Backend Services / Resources
107117
Bucket[Storage Bucket]
108118
KVStore[Key-Value Store]
109119
More[...]
110120
111121
%% Interactions
112-
Browser -->|Opens/Closes WebSocket Connection| WS
113-
WS -->|Triggers onConnection event| Conn
114-
Browser -->|Sends Message| WS
115-
WS -->|Triggers onMessage event| Msg
116-
WS -->|Triggers onDisconnect event| Disc
122+
Browser -->|Connect| WS
123+
Browser <-->|Message| WS
124+
Browser -->|Disconnect| WS
125+
WS -->|Connect| Conn
126+
WS <-->|Message| Msg
127+
WS -->|Disconnect| Disc
117128
118129
%% Backend Interactions for onMessage
119-
Msg -->|Manages/Uploads/Downloads files| Bucket
120-
Msg -->|Reads/Writes key data| KVStore
130+
Msg -->|Read/Write| Bucket
131+
Msg -->|Read/Write| KVStore
121132
Msg -->|Other services/APIs| More
122133
123134
classDef default line-height:1;
124135
classDef edgeLabel line-height:2;
125136
```
126137

127-
- The **Client Browser** opens a WebSocket connection.
128-
- The **WebSocket** handles the connection lifecycle:
129-
- When the connection opens, it triggers the **onConnect** service.
130-
- Once the connection is established, messages from the client trigger the **onMessage** service.
131-
- When the connection closes, it triggers the **onDisconnect** service.
132-
- The **onMessage**, **onConnect** and **onDisconnect** handlers:
138+
- The **Client** opens a WebSocket connection.
139+
- The **WebSocket API** handles the connection lifecycle:
140+
- When the connection opens, it triggers the **onConnect** callback function.
141+
- Once the connection is established, messages from the client trigger the **onMessage** callback function.
142+
- When the connection closes, it triggers the **onDisconnect** callback function.
143+
- The **onMessage**, **onConnect** and **onDisconnect** callbacks:
144+
- Are contained within one or more Services, accepting events from the WebSocket API.
133145
- Interact with other cloud resources e.g. Buckets, KeyValue stores and APIs.
134146

135147
## Example: Sharing resources
136148

137-
Deploy multiple APIs and other entrypoints into an application that can access shared resources.
149+
Deploy multiple services, behind shared API Gateways and interact with other shared resources.
138150

139151
```mermaid
140152
flowchart TD
141153
%% Actors
142-
Browser[Client Browser]
154+
Client1[Alice]
155+
Client2[Bob]
143156
144157
%% Nitric Application Containers (APIs)
145-
API_Read[HTTP API - Read API Gateway]
146-
API_Write[HTTP API - Write API Gateway]
147-
148-
Other[Other Resources]
158+
Api[api.example.com]
149159
150160
%% Services for respective API routes
151-
ReadService[GET Route]
152-
WriteService[POST Route]
161+
UserSrv[Orders Service]
162+
AdminSrv[Orders Mgmt Service]
153163
154164
%% Backend Services / Resources
155-
Bucket[AWS S3 Bucket]
156-
RDS[AWS RDS/Aurora]
165+
Bucket[Invoices Bucket]
157166
158167
%% Interactions from the client to each API
159-
Browser -->|Sends HTTP Request| API_Read
160-
Browser -->|Sends HTTP Request| API_Write
168+
Client1 -->|HTTP Request| Api
169+
Client2 -->|HTTP Request| Api
161170
162171
%% API triggers to their respective services
163-
API_Read -->|Triggers Service| ReadService
164-
API_Write -->|Triggers Service| WriteService
172+
Api -->|GET: /orders| UserSrv
173+
Api -->|PUT: /users/1/orders/2| AdminSrv
165174
166175
%% Common backend resource interactions from the read service
167-
ReadService -->|Retrieves files| Bucket
168-
ReadService -->|Queries data| RDS
176+
UserSrv -->|Read| Bucket
169177
170178
%% Common backend resource interactions from the write service
171-
WriteService -->|Uploads files| Bucket
172-
WriteService -->|Updates data| RDS
173-
WriteService -->Other
179+
AdminSrv -->|Read/Write| Bucket
174180
classDef default line-height:1;
175181
classDef edgeLabel line-height:2;
176182
```
177183

178-
- The **Client Browser** sends HTTP requests to the **API Gateways**.
179-
- **API Gateways** and their respective service handlers are established with least privileges:
180-
- The Read API Gateway invokes the GET Route Service, which is granted read-only permissions.
181-
- The Write API Gateway invokes the POST Route Service, which is granted write-only permissions.
184+
- **Client Browsers** send HTTP requests to a shared **API Gateway**, which routes requests to the appropriate service.
185+
- The **API Gateway's** respective route handlers (services) are established with least privileges:
186+
- The `Orders Service`, can be restricted to read-only permissions to the Invoices Bucket.
187+
- The `Orders Management Service`, is instead granted both read and write permissions to the Invoices Bucket.
182188

183189
## Example: Multiple entry points
184190

185-
A Nitric application can have multiple entry points, such as an **HTTP API Gateway**, a **Scheduled Event**, and a **WebSocket API** all sharing the same resources.
191+
A Nitric application can also have multiple entry points, such as multiple **HTTP API Gateways** and a **Schedule**, all sharing specific common resources.
186192

187193
```mermaid
188194
flowchart TD
195+
%% Actors
196+
Client1[Alice]
197+
Client2[Bob]
198+
Schedule[Archive Orders]
189199
190-
Browser[Client Browser]
191-
WSClient[WebSocket Client]
192-
Scheduled[Scheduled Event]
193-
194-
API_Read[HTTP API - Read]
195-
API_Write[HTTP API - Write]
196-
WS_API[WebSocket API]
197-
198-
ReadService[GET Route]
199-
WriteService[POST Route]
200-
ScheduledJob[Scheduled Task]
201-
202-
Bucket[AWS S3 Bucket]
203-
RDS[AWS RDS/Aurora]
204-
Other[Other Shared Resources]
205-
206-
Browser -->|HTTP Request| API_Read
207-
Browser -->|HTTP Request| API_Write
208-
WSClient <-->|Bi-directional messages| WS_API
209-
210-
Scheduled -->|Triggers| ScheduledJob
200+
%% Nitric Application Containers (APIs)
201+
UserApi[public.api.example.com]
202+
AdminApi[internal.api.example.com]
211203
212-
API_Read -->|Invokes| ReadService
213-
API_Write -->|Invokes| WriteService
214-
WS_API -->|Invokes| WriteService
215-
WS_API -->|Invokes| ReadService
204+
%% Services for respective API routes
205+
UserSrv[Orders Service]
206+
AdminSrv[Orders Mgmt Service]
207+
ArchiveSrv[Archive Service]
216208
217-
ReadService -->|Query| Bucket
218-
ReadService -->|Query| RDS
209+
%% Backend Services / Resources
210+
Bucket[Invoices Bucket]
211+
Bucket2[Archive Bucket]
219212
220-
WriteService -->|Write/Upload| Bucket
221-
WriteService -->|Create/Update| RDS
213+
%% Interactions from the client to each API
214+
Client1 -->|HTTP Request| UserApi
215+
Client2 -->|HTTP Request| AdminApi
216+
Schedule -->|3am daily| ArchiveSrv
222217
223-
ScheduledJob -->|Read| Bucket
224-
ScheduledJob -->|Read/Query| RDS
225-
ScheduledJob --> Other
218+
%% API triggers to their respective services
219+
UserApi -->|GET: /orders| UserSrv
220+
AdminApi -->|PUT: /users/1/orders/2| AdminSrv
226221
222+
UserSrv -->|Read| Bucket
223+
AdminSrv -->|Read/Write| Bucket
224+
ArchiveSrv -->|Read/Delete| Bucket
225+
ArchiveSrv -->|Write| Bucket2
227226
classDef default line-height:1;
228227
classDef edgeLabel line-height:2;
229228
```
230229

231-
- **Backend resources** (e.g. Key/Value Store, Bucket, RDS) are shared and accessed with **least-privilege** access from each service.
230+
- **Client Browsers** send HTTP requests to different **API Gateways**, which route requests to the appropriate service.
231+
- The **API Gateway's** respective route handlers (services) are established with least privileges:
232+
- The `Orders Service`, can be restricted to read-only permissions to the Invoices Bucket.
233+
- The `Orders Management Service`, is instead granted both read and write permissions to the Invoices Bucket.
234+
- A **Schedule** triggers the `Archive Service` to read and delete from the Invoices Bucket and write to the Archive Bucket.

0 commit comments

Comments
 (0)