# ilkerdagli/cdk-lambda-recaptcha-authorizer architecture

> Architecture diagram of the GitHub repository ilkerdagli/cdk-lambda-recaptcha-authorizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ilkerdagli/cdk-lambda-recaptcha-authorizer
- Repository: https://github.com/ilkerdagli/cdk-lambda-recaptcha-authorizer

## Overview

##### System’s Main Components
- AWS API Gateway – Represents the API endpoint exposed to clients.
- ReCaptcha Authorizer Construct – A CDK construct that encapsulates the logic for adding ReCaptcha-based authorization.
- AWS Lambda Function – The function (located in the functions folder) that receives the request with the ReCaptcha token, extracts the header, and communicates with Google’s ReCaptcha API.
- External Google ReCaptcha Service – The external service that verifies the legitimacy of the ReCaptcha token.
- Client / Frontend – Any HTTP client or web page (as shown in the provided HTML example) that issues requests with the ReCaptcha token in a header.

##### Relationships and Data Flow
- The client sends an API request to the API Gateway, including the ReCaptcha token in a custom header.
- The API Gateway, configured with the ReCaptcha Authorizer, triggers the AWS Lambda function.
- The Lambda function retrieves the ReCaptcha token from the request header and issues an HTTPS POST request to the Google ReCaptcha API along with the required secret key (and any v3-specific parameters if applicable).
- Google’s ReCaptcha API responds with a verification result.

##### Architectural Patterns and Design Principles
- Modular Design: The construct encapsulates specific functionality (ReCaptcha validation), making it plug-and-play into any AWS CDK project.
- Client-Server Interaction: Clear separation between a client (frontend), API gateway (edge proxy), Lambda (authorization logic), and external services.
- External Dependency Integration: Directly interact with Google’s API for real-time verification.
- Infrastructure as Code: Emphasize that the architecture is defined using AWS CDK constructs facilitating reproducible deployments.

##### Relevant Technologies and Frameworks
- AWS CDK (with its TypeScript-based implementation in src)
- AWS Lambda and API Gateway
- Node.js (as the runtime environment)
- Projen (for project configuration and dependency management)
- ESLint and other development tools indicated in the file tree for code quality

##### Additional Elements
- Annotations for configuration parameters: Highlight that the reCaptchaSecretKey, reCaptchaVersion, and optional parameters (v3MinScoreRequired, v3Action, challangeResponseHeaderName) are crucial for the Lambda’s operation.
- Use containers or clusters to group components that belong together. For instance, group all AWS resources in one segment showing that they operate within the same AWS account.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "AWS Infrastructure"
        APIGW["AWS API Gateway"]:::aws
        Construct["ReCaptcha Authorizer Construct"]:::aws
        Lambda["AWS Lambda Function"]:::aws
    end
    Client["Client / Frontend"]:::client
    External["External Google ReCaptcha API"]:::external

    Client -->|"sendsRequestWithToken"| APIGW
    APIGW -->|"invokes"| Construct
    Construct -->|"triggers"| Lambda
    Lambda -->|"POSTToken"| External
    External -->|"verificationResult"| Lambda
    Lambda -->|"authResult"| APIGW
    APIGW -->|"response"| Client

    click APIGW "https://github.com/ilkerdagli/cdk-lambda-recaptcha-authorizer/blob/main/src/index.ts"
    click Construct "https://github.com/ilkerdagli/cdk-lambda-recaptcha-authorizer/blob/main/src/index.ts"
    click Construct "https://github.com/ilkerdagli/cdk-lambda-recaptcha-authorizer/blob/main/src/integ.default.ts"
    click Lambda "https://github.com/ilkerdagli/cdk-lambda-recaptcha-authorizer/blob/main/functions/reCaptchaAuthorizerLambda.js"
    click Client "https://github.com/ilkerdagli/cdk-lambda-recaptcha-authorizer/blob/main/API.md"

    classDef aws fill:#9fdf9f,stroke:#0a0,stroke-width:2px;
    classDef client fill:#9cf,stroke:#03f,stroke-width:2px;
    classDef external fill:#f9e,stroke:#f00,stroke-width:2px;
```
