add architecture sections to docs

.puppeteerrc.cjs

@@ -0,0 +1,19 @@
+const isCI = !!process.env.VERCEL_ENV
+
+if (!isCI) {
+  // just use the default configuration on non vercel CI environments
+  return {}
+}
+
+/**
+ * @type {import("puppeteer").Configuration}
+ */
+module.exports = {
+  cacheDirectory: '/vercel/.cache/puppeteer',
+  executablePath:
+    '/vercel/.cache/puppeteer/chrome/linux-131.0.6778.204/chrome-linux64/chrome',
+  chrome: {
+    skipDownload: true,
+  },
+  args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
+}

chrome-dependencies.txt

@@ -0,0 +1,17 @@
+mesa-libgbm
+nss
+nspr
+at-spi2-atk
+cups-libs
+libdrm
+libXcomposite
+libXdamage
+libXext
+libXrandr
+libgbm
+libxcb
+alsa-lib
+atk
+gtk3
+pango
+libxkbcommon

cypress/e2e/broken-links.cy.ts

@@ -27,6 +27,8 @@ const IGNORED_URLS = [
   'https://www.gutenberg.org/cache/epub/42671/pg42671.txt',
   'https://stackoverflow.com/help/minimal-reproducible-example',
   'https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks',
+  'https://jwt.io',
+  'https://portal.azure.com',
 ]
 
 const isExternalUrl = (url: string) => {

dictionary.txt

@@ -236,13 +236,22 @@ EC2
 .jpg
 .pdf
 preflight
+lifecycle
+NodeJS
+priviledge
+APIS
+TLS
+SRE
+ACM
 nav
 MacOS
 quantized
 VPC
 trivy
 Trivy's
 KMS
+deployable
+VMs
 [0-9]+px
 ^.+[-:_]\w+$
 [a-z]+([A-Z0-9]|[A-Z0-9]\w+)

docs/apis.mdx

@@ -6,6 +6,8 @@ description: 'Building HTTP APIs with Nitric'
 
 Nitric has built-in support for web apps and HTTP API development. The `api` resource allows you to create APIs in your applications, including routing, middleware and request handlers.
 
+If you're interested in the architecture, provisioning, or deployment steps, they can be found [here](/architecture/apis).
+
 ## Creating APIs
 
 Nitric allows you define named APIs, each with their own routes, middleware, handlers and security.
@@ -332,7 +334,7 @@ APIs can include security definitions for OIDC-compatible providers such as [Aut
 
 APIs can be configured to automatically authenticate and allow or reject incoming requests. A `securityDefinitions` object can be provided, which _defines_ the authentication requirements that can later be enforced by the API.
 
-The security definition describes the kind of authentication to perform and the configuration required to perform it. For a [JWT](https://jwt.io/) this configuration includes the JWT issuer and audiences.
+The security definition describes the kind of authentication to perform and the configuration required to perform it. For a [JWT](https://jwt.io) this configuration includes the JWT issuer and audiences.
 
 <Note>
   Security definitions only define **available** security requirements for an

docs/architecture/apis.mdx

@@ -0,0 +1,177 @@
+---
+description: 'Learn how Nitric provisions and manages APIs across AWS, GCP, and Azure using Terraform and Pulumi.'
+---
+
+# APIs
+
+## 1. System Context
+
+**Developers** use Nitric to define required APIs and routes/methods within their application.
+
+- App code uses the [API resource](/apis) to define APIs and their routes/methods.
+- Developers define the 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 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** (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
+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
+
+### Build Sequence
+
+Here is the sequence of events that occur when a developer registers an API with Nitric, including the registration of routes, security, and middleware.
+
+```mermaid
+sequenceDiagram
+  participant Worker as App Worker(s)
+  participant SDK as Nitric SDK
+  participant Nitric as Nitric CLI
+  participant Provider as Nitric Provider <br> (plugin)
+  participant IAC as IaC <br> (e.g. Terraform)
+
+  Worker->>SDK: Register API(s)
+  SDK->>Nitric: Register API(s)
+
+  opt Authentication
+    Worker->>SDK: Register Security
+    SDK->>Nitric: Register Security
+  end
+
+  Worker->>SDK: Register Route Callback(s)
+  SDK->>Nitric: Register Route(s)
+  Worker->>SDK: Register Middleware(s)
+
+  Nitric->>Nitric: Generate OpenAPI Spec
+  Nitric->>Provider: Forward Nitric Spec
+  Provider->>IAC: Provision API Gateway
+  Provider->>IAC: Provision IAM
+```
+
+### Runtime Sequence
+
+Here is the sequence of events that occur at runtime when a client makes an HTTP request to an API registered and deployed using Nitric.
+
+```mermaid
+sequenceDiagram
+  participant Client as Client
+  participant APIGateway as API Gateway <br> (e.g. AWS API Gateway)
+  participant Auth as Auth Provider
+  participant Nitric as Nitric Runtime <br> (plugin)
+  participant SDK as Nitric SDK
+  participant Worker as App Worker
+
+  Client->>APIGateway: HTTP Request
+  opt Authentication
+    APIGateway->>Auth: Verify Token
+    APIGateway-->>Client: Unauthorized
+  end
+  APIGateway->>Nitric: Forward Request
+  Nitric->>Nitric: Convert Request Format
+  Nitric->>SDK: Route HTTP Event
+  SDK->>Worker: Execute Route Callback
+
+  Worker->>Worker: Process Request
+  Worker-->>Client: 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, defining the APIs routes, methods, middleware and auth.
+
+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 infrastructure modules, including both Terraform and Pulumi:
+
+- Terraform Modules:
+  - [AWS API Terraform Module](https://github.com/nitrictech/nitric/blob/main/cloud/aws/deploytf/.nitric/modules/api/main.tf)
+  - [GCP API Terraform Module](https://github.com/nitrictech/nitric/blob/main/cloud/gcp/deploytf/.nitric/modules/api/main.tf)
+- Pulumi Modules:
+  - [AWS API Pulumi Module](https://github.com/nitrictech/nitric/blob/main/cloud/aws/deploy/api.go)
+  - [GCP API Pulumi Module](https://github.com/nitrictech/nitric/blob/main/cloud/gcp/deploy/api.go)
+  - [Azure API Pulumi Module](https://github.com/nitrictech/nitric/blob/main/cloud/azure/deploy/api.go)