# stripe/stripe-js architecture

> Architecture diagram of the GitHub repository stripe/stripe-js, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stripe/stripe-js
- Repository: https://github.com/stripe/stripe-js

## Overview

##### Main Components

a. Core Components:
- Stripe.js Loader Module
- Type Definitions System
- Pure Module Variant
- Integration Examples

b. External Components:
- Stripe.js CDN (https://js.stripe.com)
- Client Applications
- Stripe API Backend

##### Integration Layer
- Different bundler examples (Webpack, Rollup, Parcel)
- To the main package functionality

##### Package Core Layer
- Main Module (`src/index.ts`)
- Pure Module (`src/pure.ts`)
- Shared Utilities (`src/shared.ts`)

##### Type System Layer
- API Types (`types/api/*`)
- Stripe.js Types (`types/stripe-js/*`)
- Elements Types (`types/stripe-js/elements/*`)

Key Relationships to Highlight:

- Client App → loadStripe() → Stripe.js CDN → Stripe Instance

##### Type system relationships
- API Types ←→ Stripe.js Types ←→ Elements Types

Use these visual elements:

Important Implementation Details to Include:

##### Security Flow
- PCI-compliant loading mechanism
- Script tag injection process
- CSP considerations

##### Module Variants
- Standard import path with side effects
- Pure import path without side effects
- How they differently interact with Stripe.js loading

##### Type System
- Relationship between API types and runtime functionality
- Versioning compatibility

Specific Guidelines:

##### Use a top-down approach
- [Client Applications]
- ↓
- [Package Entry Points (Standard/Pure)]
- ↓
- [Stripe.js Loading Mechanism]
- ↓
- [Stripe.js CDN]
- ↓
- [Stripe Instance]

##### A special section showing the different initialization paths
- Direct script tag inclusion
- Side-effect import
- Pure import with deferred loading

##### Notes about
- PCI compliance requirements
- Version compatibility
- Browser support
- TypeScript minimum version requirements

Keep the abstraction level focused on the package's role as a bridge between client applications and Stripe's services, while maintaining clarity about the security and type safety aspects that are crucial to this implementation.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Integration Layer"
        ClientApp["Client Applications"]
        Webpack["Webpack Example"]:::example
        Rollup["Rollup Example"]:::example
        Parcel["Parcel Example"]:::example
    end

    subgraph "Package Core Layer"
        MainModule["Main Module (loadStripe)"]:::core
        PureModule["Pure Module"]:::core
        SharedUtils["Shared Utilities"]:::core
    end

    subgraph "Type System Layer"
        APITypes["API Types"]:::types
        StripeJSTypes["Stripe.js Types"]:::types
        ElementsTypes["Elements Types"]:::types
        
        subgraph "Payment Types"
            PaymentIntents["Payment Intents"]:::types
            PaymentMethods["Payment Methods"]:::types
            SetupIntents["Setup Intents"]:::types
        end
        
        subgraph "Elements Types"
            CardElements["Card Elements"]:::types
            PaymentRequestBtn["Payment Request Button"]:::types
            AddressElement["Address Element"]:::types
        end
    end

    subgraph "External Components"
        StripeCDN["Stripe.js CDN"]:::external
        StripeAPI["Stripe API Backend"]:::external
    end

    subgraph "Build Outputs"
        StandardBuild["Standard Build"]:::output
        PureBuild["Pure Build"]:::output
    end

    %% Relationships
    ClientApp --> |Uses| MainModule
    ClientApp --> |Alternative| PureModule
    
    Webpack & Rollup & Parcel --> MainModule
    
    MainModule --> StripeCDN
    PureModule --> StripeCDN
    
    MainModule & PureModule --> SharedUtils
    
    StripeCDN --> StripeAPI
    
    APITypes --> StripeJSTypes
    StripeJSTypes --> ElementsTypes
    
    PaymentIntents & PaymentMethods & SetupIntents --> APITypes
    CardElements & PaymentRequestBtn & AddressElement --> ElementsTypes

    MainModule --> StandardBuild
    PureModule --> PureBuild

    %% Click Events
    click MainModule "https://github.com/stripe/stripe-js/blob/master/src/index.ts"
    click PureModule "https://github.com/stripe/stripe-js/blob/master/src/pure.ts"
    click SharedUtils "https://github.com/stripe/stripe-js/blob/master/src/shared.ts"
    click APITypes "https://github.com/stripe/stripe-js/tree/master/types/api/"
    click StripeJSTypes "https://github.com/stripe/stripe-js/tree/master/types/stripe-js/"
    click ElementsTypes "https://github.com/stripe/stripe-js/tree/master/types/stripe-js/elements/"
    click Webpack "https://github.com/stripe/stripe-js/tree/master/examples/webpack/"
    click Rollup "https://github.com/stripe/stripe-js/tree/master/examples/rollup/"
    click Parcel "https://github.com/stripe/stripe-js/tree/master/examples/parcel/"
    click StandardBuild "https://github.com/stripe/stripe-js/tree/master/lib/"
    click PureBuild "https://github.com/stripe/stripe-js/tree/master/pure/"
    click PaymentIntents "https://github.com/stripe/stripe-js/blob/master/types/api/payment-intents.d.ts"
    click PaymentMethods "https://github.com/stripe/stripe-js/blob/master/types/api/payment-methods.d.ts"
    click SetupIntents "https://github.com/stripe/stripe-js/blob/master/types/api/setup-intents.d.ts"
    click CardElements "https://github.com/stripe/stripe-js/blob/master/types/stripe-js/elements/card.d.ts"
    click PaymentRequestBtn "https://github.com/stripe/stripe-js/blob/master/types/stripe-js/elements/payment-request-button.d.ts"
    click AddressElement "https://github.com/stripe/stripe-js/blob/master/types/stripe-js/elements/address.d.ts"

    %% Styling
    classDef core fill:#2374ab,stroke:#000,stroke-width:2px,color:#fff
    classDef types fill:#ffd700,stroke:#000,stroke-width:2px
    classDef external fill:#4caf50,stroke:#000,stroke-width:2px,color:#fff
    classDef example fill:#ff7043,stroke:#000,stroke-width:2px,color:#fff
    classDef output fill:#9c27b0,stroke:#000,stroke-width:2px,color:#fff

    %% Legend
    subgraph Legend
        CoreComp["Core Components"]:::core
        TypeComp["Type Definitions"]:::types
        ExtComp["External Components"]:::external
        ExampleComp["Examples"]:::example
        OutputComp["Build Outputs"]:::output
    end
```
