# dozoisch/react-google-recaptcha architecture

> Architecture diagram of the GitHub repository dozoisch/react-google-recaptcha, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dozoisch/react-google-recaptcha
- Repository: https://github.com/dozoisch/react-google-recaptcha

## Overview

##### Main Components
- Component Library: Represent the overall npm package that developers import.
- Source Code Partitioning:
- Entry Point (src/index.js): Exposes the public API and exports the components.
- Recaptcha Components:
∙ recaptcha.js – encapsulates the core logic interacting with the Google API.
∙ recaptcha-wrapper.js – acts as a “loader” that asynchronously loads the external Google reCAPTCHA script and wraps the actual reCAPTCHA component.
- External Service:
- Google reCAPTCHA API: The external endpoint that serves the captcha widget and verifies user interactions.
- Testing & CI/CD:
- Tests (inside the test directory) integrating with tools like Jest.
- Configuration & build artifacts (Babel, ESLint, and GitHub Workflows) that ensure code quality and continuous integration.

##### Relationships & Data Flow
- The React application (or any host application) imports the exposed component from the library (via index.js).
- When rendered, the recaptcha-wrapper component:
- Dynamically loads the Google reCAPTCHA script.
- Instantiates the in-depth recaptcha logic (located in recaptcha.js).
- User interactions (solving the challenge) trigger callback functions (onChange, onErrored, onExpired) that pass the captcha token back to the hosting application.
- Optionally, the library supports both standard and “invisible” reCAPTCHA modes (with methods like execute and executeAsync) to control the challenge programmatically.
- Tests simulate these interactions to ensure the expected behavior and are run via the CI pipeline.

##### Architectural Patterns & Design Principles
- Encapsulation: The reCAPTCHA functionality (including script loading and API management) is encapsulated within well-defined React components.
- Separation of Concerns: The wrapping component handles asynchronous script loading and isolates its own ID space when needed (through the “isolated” prop), avoiding conflicts with other integrations on the same page.
- Extensibility: The component’s customizable props (theme, size, language, etc.) and exposed methods permit a variety of usage scenarios, empowering developers to easily integrate and extend functionality.
- Asynchronous Communication: The design leverages asynchronous loading of external resources (Google script) and promise-based execution flows (via executeAsync).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Application
    HA("Host Application"):::external

    %% React Component Library Subgraph
    subgraph "React Component Library"
        I("Entry Point (src/index.js)"):::internal
        RW("Recaptcha Wrapper (src/recaptcha-wrapper.js)"):::internal
        RC("Recaptcha Core Logic (src/recaptcha.js)"):::internal
    end

    %% External Service
    API("Google reCAPTCHA API"):::externalAPI

    %% Development & Testing Subgraph
    subgraph "Development & Testing"
        TS("Test Suite (test directory)"):::ci
        CIP("CI/CD Pipeline"):::ci
        CIP1("GitHub Workflows (.github/workflows/standard-ci.yml)"):::ci
        CIP2("Babel Configuration (.babelrc)"):::ci
        CIP3("ESLint Configuration (.eslintrc.js)"):::ci
    end

    %% Data Flow Connections
    HA -->|"imports"| I
    I -->|"exposes"| RW
    RW -->|"loads script"| API
    RW -->|"instantiates"| RC
    RC -->|"user_token_callback"| HA

    %% CI/CD internal connections
    CIP --> CIP1
    CIP --> CIP2
    CIP --> CIP3

    %% Styles
    classDef external fill:#ffeeee,stroke:#d33,stroke-width:2px;
    classDef internal fill:#e0f7ff,stroke:#339,stroke-width:2px;
    classDef externalAPI fill:#fff2cc,stroke:#993300,stroke-width:2px;
    classDef ci fill:#e6ffe6,stroke:#393,stroke-width:2px;

    %% Click Events
    click I "https://github.com/dozoisch/react-google-recaptcha/blob/master/src/index.js"
    click RW "https://github.com/dozoisch/react-google-recaptcha/blob/master/src/recaptcha-wrapper.js"
    click RC "https://github.com/dozoisch/react-google-recaptcha/blob/master/src/recaptcha.js"
    click TS "https://github.com/dozoisch/react-google-recaptcha/tree/master/test"
    click CIP1 "https://github.com/dozoisch/react-google-recaptcha/blob/master/.github/workflows/standard-ci.yml"
    click CIP2 "https://github.com/dozoisch/react-google-recaptcha/blob/master/.babelrc"
    click CIP3 "https://github.com/dozoisch/react-google-recaptcha/blob/master/.eslintrc.js"
```
