# rpo-pay/threedsecure-react architecture

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

- Interactive diagram: https://gitdiagram.com/rpo-pay/threedsecure-react
- Repository: https://github.com/rpo-pay/threedsecure-react

## Overview

##### Main System Type and Purpose
- This is a frontend‐only **React library** (written in TypeScript) that provides hooks to implement the full 3D Secure (3DS) authentication flow.
- It also includes a **demo application** under `src/` for local development and testing.

##### Break Down the File Structure into Logical Components
A. **Library Package (`lib/`)**
1. Hooks Submodule (`lib/hooks/`):
- useThreeDSecure (core hook)
- useApi, useBase64Encoder, useChallenge, useDsMethod, useThreeDSecure
2. Models Submodule (`lib/models/`):
- Domain classes/interfaces (e.g., Bucket)
3. Types Submodule (`lib/types/`):
- TypeScript definitions for requests/responses (authentication, threedsecure‐parameters, threedsecure‐result)
4. Main Entry Point (`lib/main.ts`):
- Exports all public hooks/models/types for consumers
B. **Demo Application (`src/`)**
- `src/App.tsx` and `src/main.tsx`
- Demonstrates library usage and renders challenge container
C. **Public Assets (`public/` / `index.html`)**
- Static HTML shell for the Vite dev server
D. **Build & Config**
- Vite config (`vite.config.ts`), TypeScript configs (`tsconfig.*.json`)
- NPM publishing pipeline (`.github/workflows/npm-publish.yml`)
- ESLint, Biome, GitHub Actions

##### External Services
- **3DS Core API** (baseUrl: https://api.sqala.tech/core/v1/threedsecure)
- Directory Server interactions
- Challenge rendering (IFRAME container)
- Result callbacks

##### Architectural Patterns & Data Flows
- **Library Build Pipeline** (build‐time):
- Source `.ts/.tsx` → Vite compiles → outputs ESM/CJS in `dist/` → NPM publish
- **Runtime Flow**:
- Consumer app calls `useThreeDSecure.execute()`
- Hook uses `useApi` to send requests to 3DS Core API
- Core API returns HTML challenge → injected into the containerRef (IFRAME)
- Hook listens for responses (postMessage or polling via `useDsMethod`)
- Final result passed back to the React component

- Build Tools (Vite, TS Compiler, GitHub Actions)
- Library Modules (Hooks, Models, Types, Entry Point)
- Demo App (React Components)
- Static Assets (public/index.html)
- External 3DS Core API (Directory Server, Challenge Endpoint)
- Consumer Application (could be any React app importing the library)
c. Architectural Patterns:
- **Modular Library Design**: clear separation into hooks, models, types
- **Hook‐based API**: encapsulates side effects and state management
- **External Service Integration**: plug‐and‐play via baseUrl
d. Key Technologies (label next to components):
- React, TypeScript, Vite, ESM/CJS, GitHub Actions

##### Essential Elements to Capture
- Build pipeline from source → dist → NPM
- Separation between library code and demo app
- Hook invocation flow → external 3DS API → challenge container → result handling
- Configuration boundaries (Vite, TS configs)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build Tools
    subgraph "Build Tools"
        direction TB
        VITE["Vite"]:::build
        TSC["TypeScript Compiler"]:::build
        GHA["GitHub Actions\n(npm-publish)"]:::build
    end

    %% Build Pipeline
    VITE -->|"compile & bundle"| DIST["dist/"]:::build
    TSC -->|"type-check"| DIST
    DIST -->|"publish"| NPM["NPM Registry"]:::external

    %% Library Modules
    subgraph "Library Package (lib/)" 
        direction TB
        subgraph "Hooks" 
            direction TB
            useApi["useApi"]:::code
            useBase64["useBase64Encoder"]:::code
            useChallenge["useChallenge"]:::code
            useDsMethod["useDsMethod"]:::code
            useThreeDSecureHook["useThreeDSecure"]:::code
            hooksIndex["index.ts"]:::code
        end
        subgraph "Models"
            direction TB
            bucketModel["Bucket Model"]:::code
            modelsIndex["index.ts"]:::code
        end
        subgraph "Types"
            direction TB
            authTypes["authentication.ts"]:::code
            paramsTypes["threedsecure-parameters.ts"]:::code
            resultTypes["threedsecure-result.ts"]:::code
            typesIndex["index.ts"]:::code
        end
        mainEntry["main.ts"]:::code
    end

    %% Demo Application
    subgraph "Demo App (src/)"
        direction TB
        App["App.tsx"]:::runtime
        AppStyles["App.css"]:::runtime
        MainDemo["main.tsx"]:::runtime
        IndexStyles["index.css"]:::runtime
        subgraph "Demo Hooks"
            direction TB
            cardVaultHook["useCardVault.ts"]:::runtime
            demoHooksIndex["index.ts"]:::runtime
        end
        DemoAssets["assets/"]:::runtime
        ViteEnv["vite-env.d.ts"]:::runtime
    end

    %% Public Assets
    subgraph "Public Assets"
        direction TB
        PublicDir["public/"]:::assets
        HTMLShell["index.html"]:::assets
    end

    %% Consumer App
    ConsumerApp["Consumer React App"]:::runtime

    %% External Service
    CoreAPI["3DS Core API"]:::external
    DirectoryServer["Directory Server"]:::external
    ChallengeEndpoint["Challenge Endpoint"]:::external

    %% Runtime Flow
    ConsumerApp -->|"import hook"| useThreeDSecureHook
    useThreeDSecureHook -->|"HTTPS request"| CoreAPI
    CoreAPI -->|"HTML challenge"| useChallenge
    useChallenge -->|"inject IFRAME"| App
    useDsMethod -->|"poll/postMessage"| CoreAPI
    useThreeDSecureHook -->|"result callback"| ConsumerApp

    %% Build-time to Demo
    DIST -->|"link locally"| DemoAppLink["Demo uses built library"]:::runtime
    DemoAppLink --> App

    %% Configuration
    subgraph "Config & Scripts"
        direction TB
        ViteConfig["vite.config.ts"]:::config
        TSConfigAll["tsconfig*.json"]:::config
        ESLint["eslint.config.js"]:::config
        Biome["biome.json"]:::config
        PublishWF[".github/workflows/npm-publish.yml"]:::config
    end

    %% Asset Connections
    PublicDir -->|"served by Vite"| DemoAppLink
    HTMLShell --> DemoAppLink

    %% Class Definitions
    classDef build fill:#dddddd,stroke:#888888;
    classDef code fill:#cfe2f3,stroke:#2a6f97;
    classDef runtime fill:#fce5cd,stroke:#c77c0a;
    classDef external fill:#d9ead3,stroke:#38761d;
    classDef assets fill:#fff2cc,stroke:#b8860b;
    classDef config fill:#ead1dc,stroke:#a64d79;

    %% Click Events
    click useApi "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/hooks/useApi.ts"
    click useBase64 "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/hooks/useBase64Encoder.ts"
    click useChallenge "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/hooks/useChallenge.ts"
    click useDsMethod "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/hooks/useDsMethod.ts"
    click useThreeDSecureHook "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/hooks/useThreeDSecure.ts"
    click hooksIndex "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/hooks/index.ts"
    click bucketModel "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/models/bucket.ts"
    click modelsIndex "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/models/index.ts"
    click authTypes "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/types/authentication.ts"
    click paramsTypes "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/types/threedsecure-parameters.ts"
    click resultTypes "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/types/threedsecure-result.ts"
    click typesIndex "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/types/index.ts"
    click mainEntry "https://github.com/rpo-pay/threedsecure-react/blob/main/lib/main.ts"
    click App "https://github.com/rpo-pay/threedsecure-react/blob/main/src/App.tsx"
    click AppStyles "https://github.com/rpo-pay/threedsecure-react/blob/main/src/App.css"
    click MainDemo "https://github.com/rpo-pay/threedsecure-react/blob/main/src/main.tsx"
    click IndexStyles "https://github.com/rpo-pay/threedsecure-react/blob/main/src/index.css"
    click cardVaultHook "https://github.com/rpo-pay/threedsecure-react/blob/main/src/hooks/useCardVault.ts"
    click demoHooksIndex "https://github.com/rpo-pay/threedsecure-react/blob/main/src/hooks/index.ts"
    click DemoAssets "https://github.com/rpo-pay/threedsecure-react/tree/main/src/assets/"
    click ViteEnv "https://github.com/rpo-pay/threedsecure-react/blob/main/src/vite-env.d.ts"
    click PublicDir "https://github.com/rpo-pay/threedsecure-react/tree/main/public/"
    click HTMLShell "https://github.com/rpo-pay/threedsecure-react/blob/main/index.html"
    click ViteConfig "https://github.com/rpo-pay/threedsecure-react/blob/main/vite.config.ts"
    click TSConfigAll "https://github.com/rpo-pay/threedsecure-react/blob/main/tsconfig.json"
    click TSConfigAll "https://github.com/rpo-pay/threedsecure-react/blob/main/tsconfig.app.json"
    click TSConfigAll "https://github.com/rpo-pay/threedsecure-react/blob/main/tsconfig.lib.json"
    click TSConfigAll "https://github.com/rpo-pay/threedsecure-react/blob/main/tsconfig.node.json"
    click ESLint "https://github.com/rpo-pay/threedsecure-react/blob/main/eslint.config.js"
    click Biome "https://github.com/rpo-pay/threedsecure-react/blob/main/biome.json"
    click PublishWF "https://github.com/rpo-pay/threedsecure-react/blob/main/.github/workflows/npm-publish.yml"
```
