docs: internal modules

Author: xstelea

docs/modules.md

@@ -0,0 +1,103 @@
+# Radix dApp Toolkit internal modules
+
+```mermaid
+flowchart TD
+    %% Main Entry
+    M[dApp toolkit modules]
+
+    %% Core Modules with Implementation Files
+    M ---> WR[Wallet Request]
+    M ---> S[Storage]
+    M ---> E[Environment]
+    M ---> CB[Connect Button]
+    M ---> G[Gateway]
+    M ---> ST[State]
+
+    %% Wallet Request Components
+    WR ---> WRC1[data-request]
+    WR ---> WRC2[pre-authorization-request]
+    WR ---> WRC3[session]
+    WR ---> WRC4[identity]
+    WR ---> WRC5[encryption]
+    WR ---> WRC7[Transport]
+    WR ---> WRC8[request-resolver]
+    WR ---> WRC9[request-items]
+
+    %% Transport Submodules
+    WRC7 ---> T1[radix-connect-relay]
+    WRC7 ---> T2[connector-extension]
+
+    %% Style Definitions
+    classDef mainModule fill:#282a36,stroke:#ff79c6,stroke-width:2px,color:#f8f8f2,font-family:Monaco,font-weight:bold,font-size:14px;
+    classDef implementation fill:#44475a,stroke:#8be9fd,stroke-width:1px,color:#50fa7b,font-family:Monaco,font-size:12px;
+    classDef space fill:none,stroke:none;
+
+    %% Class Assignments
+    class WR,S,E,CB,G,ST mainModule;
+    class WRC1,WRC2,WRC3,WRC4,WRC5,WRC7,WRC8,WRC9 implementation;
+    class T1,T2,T3 implementation;
+
+    %% Link Styling
+    linkStyle default stroke:#bd93f9,stroke-width:2px;
+```
+
+### Wallet Request
+
+The central module for handling all wallet-related interactions. It coordinates communication between the dApp and the Radix Wallet through various submodules:
+
+- **data-request**: Manages data requests to and from the wallet
+- **pre-authorization-request**: Handles wallet pre-authorization requests
+- **session**: Manages wallet connection sessions
+- **identity**: Handles user identity in context of wallet sessions
+- **encryption**: Provides encryption services for secure communication
+- **transport**: Manages different transport layers for wallet communication
+- **request-resolver**: Matches outgoing requests to incoming responses
+- **request-items**: Internal record of all requests
+
+#### Transport Layer
+
+The transport module supports multiple communication channels:
+
+- **radix-connect-relay**: Handles communication through deep link and the Radix Connect relay service
+- **connector-extension**: Manages browser extension-based connections
+
+### Storage
+
+Manages persistent data storage for the dApp, handling:
+
+- Wallet connection states
+- Session information
+- Cache management
+
+### Environment
+
+Handles environment-specific configuration and detection:
+
+- Platform-specific features
+- Runtime configuration
+- Environment-specific optimizations
+
+### Connect Button
+
+Provides the UI component for wallet connection:
+
+- User interface for wallet connection
+- Connection state management
+- Visual feedback for connection states
+- Customizable styling and behavior
+
+### Gateway
+
+Manages communication with the Radix Gateway:
+
+- API endpoint management
+- Transaction status polling
+
+### State
+
+Manages the global state of the dApp toolkit:
+
+- Connection state
+- Wallet state
+- Request states
+- Event management

docs/request-life-cycle.md

@@ -0,0 +1,53 @@
+# Wallet request life-cycle
+
+```mermaid
+%%{init: { 'theme': 'dark' } }%%
+sequenceDiagram
+    participant App as dApp
+    participant WR as WalletRequestModule
+    participant TR as Transport
+    participant RR as RequestResolver
+    participant W as Wallet
+    participant S as State
+
+    Note over App,S: Wallet Request Lifecycle
+
+    App->>WR: sendRequest()
+
+    Note right of WR: Request Initialization
+    WR->>WR: Create walletInteraction
+    WR->>WR: Add request to requestItemModule
+    WR->>TR: Send via appropriate transport
+
+    Note right of TR: Transport Layer
+    TR->>W: Send request to wallet
+    TR-->>RR: Mark request as sent
+    TR->>RR: Register for response
+
+    Note right of W: Wallet Processing
+    W->>W: Process request
+    W-->>TR: Send response
+
+    Note right of RR: Response Resolution
+    TR->>RR: Forward wallet response
+    RR->>RR: Match request to response
+    RR->>RR: Resolve request
+
+    alt Data Request
+        RR->>S: Update wallet data
+        RR->>WR: Return wallet data
+    else Transaction Request
+        RR->>RR: Poll transaction status
+        RR->>WR: Return transaction result
+    else Pre-authorization Request
+        RR->>RR: Update request status
+        RR->>WR: Return authorization result
+    end
+
+    WR->>App: Return result
+
+    Note right of WR: Cleanup
+    WR->>RR: Update request status
+    WR->>WR: Update button status
+    WR->>WR: Cleanup if oneTime request
+```

docs/transport-ce.md

@@ -0,0 +1,56 @@
+# Connector extension transport
+
+```mermaid
+%%{init: { 'theme': 'dark' } }%%
+sequenceDiagram
+    participant App as WalletRequestModule
+    participant CE as ConnectorExtensionModule
+    participant Sub as JS Events
+    participant Ext as Connector Extension
+    participant W as Wallet
+
+    Note over App,W: Extension Transport Flow
+
+    App->>CE: sendWalletInteraction(interaction)
+
+    Note right of CE: Extension Status Check
+    CE->>Sub: getExtensionStatus
+    Sub->>Ext: dispatchEvent(extensionStatus)
+    Ext-->>Sub: MessageLifeCycleExtensionStatusEvent
+     Sub-->>CE: CE status
+
+    Note right of CE: Request Setup
+    CE->>CE: wrapWalletInteraction()
+
+    Note right of CE: Send Request
+    CE->>Sub: send wallet interaction
+    Sub->>Ext: dispatchEvent(interaction)
+    Ext->>W: Forward request to wallet
+
+    Note right of CE: Response Handling Setup
+    par Response Listeners
+        CE->>Sub: Listen for wallet response
+        and
+        CE->>Sub: Listen for lifecycle events
+        and
+        CE->>Sub: Listen for cancellation
+    end
+
+    alt Successful Response
+        W-->>Ext: Send response
+        Ext-->>Sub: dispatchEvent(incomingMessage)
+        Sub->>CE: handle wallet response
+        CE-->>App: Return wallet response
+    else Cancellation
+        App->>CE: cancelRequest()
+        CE->>Sub: Send cancel request
+        Sub->>Ext: dispatchEvent(cancelRequest)
+        Ext-->>Sub: requestCancelSuccess/Fail
+        CE-->>App: Return cancellation result
+    else Extension Missing
+        CE->>CE: Timer expires
+        CE-->>App: Return missingExtension error
+    end
+
+    CE->>Sub: Unsubscribe all listeners
+```

docs/transport-rcr.md

@@ -0,0 +1,46 @@
+# Radix Connect Relay Transport
+
+```mermaid
+%%{init: { 'theme': 'dark' } }%%
+sequenceDiagram
+participant App as WalletRequestModule
+participant RCR as RadixConnectRelayModule
+participant IM as IdentityModule
+participant SM as SessionModule
+participant DL as DeepLinkModule
+participant API as Radix Connect Relay
+participant W as Wallet
+
+    Note over App,W: Mobile Flow with Radix Connect Relay
+
+    App->>RCR: sendToWallet(walletInteraction)
+
+    Note right of RCR: Session & Identity Setup
+    RCR->>SM: get session
+    RCR->>IM: get dApp identity
+
+    Note right of IM: Create Request Signature
+    IM->>IM: create signature
+
+    Note right of RCR: Prepare Deep Link
+    RCR->>RCR: base64urlEncode(walletInteraction)
+
+    Note right of RCR: Send to Wallet
+    RCR->>DL: deep link to wallet
+
+    DL->>W: deep link to wallet with params
+
+    Note right of RCR: Response Polling
+    loop Check Relay
+        RCR->>API: getResponses(sessionId)
+        API-->>RCR: WalletResponse[]
+
+        Note right of RCR: Decrypt Response
+        RCR->>IM: calculateSharedSecret()
+        RCR->>RCR: decryptWalletResponse()
+    end
+
+    RCR-->>App: Return wallet response
+
+    Note over App,W: Response Processing Complete
+```