# displayful/turnstiled architecture

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

- Interactive diagram: https://gitdiagram.com/displayful/turnstiled
- Repository: https://github.com/displayful/turnstiled

## Overview

##### Project type and purpose
- This is a Ruby gem (turnstiled) designed to plug into a Ruby on Rails application.
- Its sole purpose is to streamline the integration of Cloudflare Turnstile CAPTCHA—automating asset injection, helper methods, controller concerns, and server-side verification.

##### File structure
- Top-level files:
- turnstiled.gemspec, Gemfile/Gemfile.lock – gem metadata and dependencies
- Rakefile, bin/ scripts – development tasks and wrappers for tests and linting
- app/
- assets/config/turnstiled/manifest.js – asset pipeline manifest
- app/javascript/turnstiled – Stimulus controller and mock widget for development/testing
- lib/turnstiled
- engine.rb – Rails::Engine to hook into asset pipeline and isolate namespace
- controller_methods.rb – Concern injecting `verify_turnstile_request`
- view_helper.rb – Helper methods (`turnstile_javascript_tag`, `turnstile_tag`)
- verifier.rb – Server-side verification logic against Cloudflare API
- test/ – unit tests for each module

##### Extract architectural insights from the README
- The gem:
- Exposes view helpers to embed JS and widget markup
- Provides a mock widget in dev/test via Stimulus for predictable callbacks
- Offers a controller concern to verify incoming tokens
- Makes outbound HTTPS calls to Cloudflare’s verification endpoint

##### Main components
a. Rails Host Application
– Uses turnstiled Engine under the hood
– Calls helper methods in views and controller concerns in controllers
b. Turnstiled Engine (Railtie)
– Mounts assets into Rails’ asset pipeline
– Auto-loads Stimulus controllers and styles
c. ViewHelper Module
– Renders `<script>` tags and `
` containers
d. Front-end JavaScript
– Official Turnstile widget (production)
– MockTurnstileWidget (development/test)
– Stimulus controller listens for widget callback, injects token into form
e. Rails Controller Concern
– `verify_turnstile_request` runs before actions to enforce verification
f. Verifier Module
– Performs HTTP POST to `https://challenges.cloudflare.com/turnstile/v0/siteverify`
– Parses JSON response, raises or returns boolean
g. Cloudflare Turnstile Service (external)

##### Relationships and data flows
1. User loads a Rails view →
ViewHelper injects `<script>` and widget markup
2. Browser requests Turnstile JS from Cloudflare CDN →
Widget is rendered client-side
3. User solves captcha →
Widget JS fires callback → Stimulus controller captures token →
Token appended to form field `cf-turnstile-response`
4. Form submitted → Rails controller action invoked →
Controller Concern extracts token → calls Verifier
5. Verifier POSTs token+secret to Cloudflare →
Cloudflare returns success/failure →
Controller Concern allows or rejects request

##### Architectural patterns and design principles
- Rails Engine pattern for plug-and-play integration
- MVC extension via controller concerns and view helpers
- Asset Pipeline + Stimulus for encapsulated front-end behavior
- Single-Responsibility: each module has one clear purpose
- Environment-aware code paths (mock vs. real widget)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Rails Host Application
    subgraph "Rails Application" 
        direction TB
        App["Rails App"]:::rails-app
        Helpers["ViewHelper\n(lib/turnstiled/view_helper.rb)"]:::gem
        Concern["Controller Concern\n(verify_turnstile_request)\n(lib/turnstiled/controller_methods.rb)"]:::gem
        App -->|"include helpers"| Helpers
        App -->|"include concern"| Concern
    end

    %% Turnstiled Engine
    subgraph "Turnstiled Engine (Gem)" 
        direction TB
        Entry["Gem Entry Point\n(lib/turnstiled.rb)"]:::gem
        Engine["Engine (Rails::Engine)\n(lib/turnstiled/engine.rb)"]:::gem
        Verifier["Verifier Module\n(lib/turnstiled/verifier.rb)"]:::gem
        AssetsConfig["Asset Manifest\n(app/assets/config/turnstiled/manifest.js)"]:::gem
        Stimulus["Stimulus Controller\n(app/javascript/turnstiled/controllers/turnstile_controller.js)"]:::gem
        MockWidget["Mock Widget\n(app/javascript/turnstiled/mock_turnstile_widget.js)"]:::gem

        Entry --> Engine
        Engine --> AssetsConfig
        Engine --> Stimulus
        Engine --> MockWidget
        Entry --> Helpers
        Entry --> Concern
        Concern --> Verifier
    end

    %% Browser & Front-End Flow
    Browser["User Browser"]:::external
    CloudflareCDN["Cloudflare CDN\n(Widget JS)"]:::external
    Browser -->|"HTTP GET script"| CloudflareCDN
    Browser -->|"Loads Stimulus Controller"| Stimulus
    Stimulus -->|"Render Widget"| Browser
    Browser -->|"Callback with token"| Stimulus
    Stimulus -->|"Append token to form"| Browser

    %% Form Submission and Verification
    Browser -->|"Submit form with token"| App
    Concern -->|"calls verify_turnstile_request"| Verifier
    Verifier -->|"HTTP POST JSON"| CloudflareAPI["Cloudflare Verification API\n(https://challenges.cloudflare.com/turnstile/v0/siteverify)"]:::external
    CloudflareAPI -->|"JSON response"| Verifier
    Verifier -->|"success/failure"| Concern

    %% Click Events
    click Engine "https://github.com/displayful/turnstiled/blob/main/lib/turnstiled/engine.rb"
    click Helpers "https://github.com/displayful/turnstiled/blob/main/lib/turnstiled/view_helper.rb"
    click Concern "https://github.com/displayful/turnstiled/blob/main/lib/turnstiled/controller_methods.rb"
    click Verifier "https://github.com/displayful/turnstiled/blob/main/lib/turnstiled/verifier.rb"
    click AssetsConfig "https://github.com/displayful/turnstiled/blob/main/app/assets/config/turnstiled/manifest.js"
    click Stimulus "https://github.com/displayful/turnstiled/blob/main/app/javascript/turnstiled/controllers/turnstile_controller.js"
    click MockWidget "https://github.com/displayful/turnstiled/blob/main/app/javascript/turnstiled/mock_turnstile_widget.js"
    click Entry "https://github.com/displayful/turnstiled/blob/main/lib/turnstiled.rb"

    %% Styles
    classDef rails-app fill:#e0f7e9,stroke:#34a853,stroke-width:2px
    classDef gem fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
    classDef external fill:#fff4e5,stroke:#fbbc04,stroke-width:2px
```
