# nenes25/eicaptcha architecture

> Architecture diagram of the GitHub repository nenes25/eicaptcha, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nenes25/eicaptcha
- Repository: https://github.com/nenes25/eicaptcha

## Overview

##### Project Type and Purpose
- Type: An open-source PrestaShop module that injects Google reCAPTCHA (V2/V3) into various customer-facing forms of a PrestaShop 1.7+ shop.
- Purpose: Enhance form security by validating user submissions against Google’s reCAPTCHA service, via PrestaShop hooks and controller overrides.

##### File Structure
- Top-level Entrypoints
– eicaptcha.php: Module bootstrap, registration of hooks, installation/uninstallation logic.
– index.php stubs (security).
- Overrides
– override/controllers/front/AuthController.php
– override/controllers/front/OrderController.php
– override/modules/contactform/contactform.php
These intercept form-display and form-submit logic in PrestaShop core/controllers and core modules.
- Source (src/)
– Installer.php: module install/upgrade scripts, writes configuration.
– ConfigForm.php: defines back-office configuration form fields (reCAPTCHA keys, options).
– Debugger.php: diagnostic utilities (used in admin debug template).
- Views (views/)
– templates/hook/*.tpl: hook display templates for forms.
– js/css: frontend assets, reCAPTCHA loader scripts.
- Tests
– PHPStan, PHPCS, functional PHP tests, Playwright E2E tests (contact form, registration, newsletter).
- CI/CD
– .github/workflows: PHP linting, release build.
– composer.json: pulls in google/recaptcha package.

##### README Insights
- Registers on hooks: displayCustomerAccountForm, displayContactForm, displayNewsletterRegistration, custom hooks.
- Supports both V2 (visible) and V3 (invisible) Google reCAPTCHA.
- Relies on composer for recaptcha library.
- Overrides specific controllers rather than replacing core logic entirely.

##### Main Components & Interactions
a. PrestaShop Core
– Front controllers (AuthController, OrderController)
– Core ContactForm module
– Hook dispatcher
b. eicaptcha Module
– Module bootstrap (eicaptcha.php)
– Installer (writes DB settings, registers hooks)
– ConfigForm (back-office UI)
– Debugger (admin debug display)
– Override classes (intercept form submission, validation)
– Hook display templates (inject reCAPTCHA widget)
– Asset loaders (JS/CSS)
c. External Service
– Google reCAPTCHA API (site & secret keys)
d. Developer Tooling
– Composer (dependency mgr)
– CI workflows (static analysis, tests)

##### Relationships & Data Flows
- At page-render: PrestaShop core dispatches hook → eicaptcha hook handler injects reCAPTCHA widget via template and JS asset.
- On form submit: Overridden controller method intercepts submission → eicaptcha validation logic calls Google API via composer library → on success, delegates back to core controller; on failure, returns error.
- Back-office: Admin config page reads/writes reCAPTCHA keys via ConfigForm.
- CI: Push → GitHub Actions runs PHP linting, static analysis, functional & E2E tests against a test PrestaShop instance.

##### Architectural Patterns & Principles
- Extension via Hooks and Overrides (PrestaShop plugin model)
- Separation of Concerns:
– Presentation (templates, JS, CSS)
– Configuration (ConfigForm)
– Business Logic (validation, installer)
– Diagnostics (Debugger)
- Dependency Management via Composer
- Test-Driven Quality (PHPStan, Playwright)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% PrestaShop Core
    subgraph "PrestaShop Core"
        direction TB
        Dispatcher["Hook Dispatcher"]:::core
        PS_Auth["AuthController"]:::core
        PS_Order["OrderController"]:::core
        PS_ContactModule["ContactForm Module"]:::core
    end

    %% eicaptcha Module
    subgraph "eicaptcha Module"
        direction TB
        Entrypoint["Entrypoint (eicaptcha.php)"]:::module
        Installer["Installer (Install/Upgrade Logic)"]:::module
        ConfigForm["Configuration Form"]:::module
        Debugger["Debugger (Admin Diagnostics)"]:::module

        subgraph "Overrides"
            direction TB
            O_Auth["AuthController Override"]:::module
            O_Order["OrderController Override"]:::module
            O_ContactMod["ContactForm Override"]:::module
        end

        subgraph "Hook Display Templates"
            direction TB
            T_CustAcc["Customer Account Form Template"]:::module
            T_News["Newsletter Registration Template"]:::module
            T_Verif["Generic Verification Template"]:::module
        end

        subgraph "Assets"
            direction TB
            CSS["CSS Assets"]:::module
            JS_V2["JS Contact Form V2"]:::module
            JS_V3["JS Contact Form V3"]:::module
            JS_Admin["Admin JS (Debug UI)"]:::module
            AdminTpl["Admin Template (debug.tpl)"]:::module
        end
    end

    %% External Service
    Google["Google reCAPTCHA API"]:::external

    %% Development & Deployment
    subgraph "Development & Deployment"
        direction TB
        Composer["composer.json"]:::tool
        CI_Lint["GitHub Actions: PHP Lint & Tests"]:::tool
        CI_Build["GitHub Actions: Build & Release"]:::tool
        TestsPHP["PHP Tests"]:::tool
        TestsE2E["Playwright E2E Tests"]:::tool
    end

    %% Relationships
    Entrypoint -->|registers hooks| Dispatcher
    Installer -->|writes config| ConfigForm
    Entrypoint --> Installer
    ConfigForm -->|reads/writes keys| Entrypoint
    Entrypoint --> Debugger

    Dispatcher -->|renders widget| T_CustAcc
    Dispatcher -->|renders widget| T_News
    Dispatcher -->|renders widget| T_Verif
    T_CustAcc --> CSS
    T_CustAcc --> JS_V2
    T_CustAcc --> JS_V3

    PS_Auth -->|form submit| O_Auth
    PS_Order -->|form submit| O_Order
    PS_ContactModule -->|form submit| O_ContactMod

    O_Auth -->|validate| Google
    O_Order -->|validate| Google
    O_ContactMod -->|validate| Google

    O_Auth -->|delegate back| PS_Auth
    O_Order -->|delegate back| PS_Order
    O_ContactMod -->|delegate back| PS_ContactModule

    ConfigForm -->|UI| Entrypoint
    Debugger -->|admin view| AdminTpl

    Composer -->|dependency| Entrypoint
    Composer -->|dependency| Google

    CI_Lint -->|runs| TestsPHP
    CI_Lint -->|runs| TestsE2E
    CI_Build -->|builds module| Entrypoint

    %% Click Events
    click Entrypoint "https://github.com/nenes25/eicaptcha/blob/17/eicaptcha.php"
    click Installer "https://github.com/nenes25/eicaptcha/blob/17/src/Installer.php"
    click ConfigForm "https://github.com/nenes25/eicaptcha/blob/17/src/ConfigForm.php"
    click Debugger "https://github.com/nenes25/eicaptcha/blob/17/src/Debugger.php"
    click O_Auth "https://github.com/nenes25/eicaptcha/blob/17/override/controllers/front/AuthController.php"
    click O_Order "https://github.com/nenes25/eicaptcha/blob/17/override/controllers/front/OrderController.php"
    click O_ContactMod "https://github.com/nenes25/eicaptcha/blob/17/override/modules/contactform/contactform.php"
    click T_CustAcc "https://github.com/nenes25/eicaptcha/blob/17/views/templates/hook/hookDisplayCustomerAccountForm.tpl"
    click T_News "https://github.com/nenes25/eicaptcha/blob/17/views/templates/hook/hookDisplayNewsletterRegistration.tpl"
    click T_Verif "https://github.com/nenes25/eicaptcha/blob/17/views/templates/hook/hookDisplayEicaptchaVerification.tpl"
    click CSS "https://github.com/nenes25/eicaptcha/blob/17/views/css/eicaptcha.css"
    click JS_V2 "https://github.com/nenes25/eicaptcha/blob/17/views/js/eicaptcha-contact-form-v2.js"
    click JS_V3 "https://github.com/nenes25/eicaptcha/blob/17/views/js/eicaptcha-contact-form-v3.js"
    click JS_Admin "https://github.com/nenes25/eicaptcha/blob/17/views/js/admin.js"
    click AdminTpl "https://github.com/nenes25/eicaptcha/blob/17/views/templates/admin/debug.tpl"
    click CI_Lint "https://github.com/nenes25/eicaptcha/blob/17/.github/workflows/php.yml"
    click CI_Build "https://github.com/nenes25/eicaptcha/blob/17/.github/workflows/build-release.yml"
    click Composer "https://github.com/nenes25/eicaptcha/blob/17/composer.json"
    click TestsPHP "https://github.com/nenes25/eicaptcha/tree/17/tests/php/"
    click TestsE2E "https://github.com/nenes25/eicaptcha/tree/17/tests/functionnal/e2e/"

    %% Styles
    classDef core fill:#d0e7ff,stroke:#4a90e2,stroke-width:1px
    classDef module fill:#dff3d8,stroke:#6abf69,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#f5a623,stroke-width:1px
    classDef tool fill:#f2f2f2,stroke:#999999,stroke-width:1px
```
