# dibakarsutradhar/bkash-rs architecture

> Architecture diagram of the GitHub repository dibakarsutradhar/bkash-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dibakarsutradhar/bkash-rs
- Repository: https://github.com/dibakarsutradhar/bkash-rs

## Overview

bkash-rs is a Rust client library, not an application server. The architecture is organized around one shared client core, several feature-gated product facades, a typed model layer, and a small set of utility subsystems for auth, transport, errors, and webhook verification.

1. The main entrypoint is `Bkash` in `src/client.rs`. It is a cheaply cloneable handle that owns shared internal state and is the only thing consumers need to keep around. Product-specific APIs are obtained from it through accessors such as `bkash.tokenized()`, `bkash.checkout()`, `bkash.auth_capture()`, and `bkash.subscriptions()`.

2. Configuration lives in `src/config.rs`. `ConfigBuilder` validates credentials, environment, timeout, retry count, base URL, and optional custom HTTP client. `Environment` selects sandbox vs production and determines the API host family. This is the boundary where user inputs become runtime configuration.

3. The outbound HTTP boundary is `src/transport.rs`. It wraps `reqwest`, applies timeouts, retries transient failures with backoff, and is responsible for attaching auth tokens to requests. All network calls to bKash flow through this layer rather than directly from the product modules.

4. Authentication is centralized in `src/token.rs` and the transport. The client caches the bKash access token, transparently grants or refreshes it when needed, and reuses it across all product accessors. The README’s `build_and_connect()` behavior indicates the token cache can be warmed during client construction.

5. Product logic is split into separate façades in `src/tokenized.rs`, `src/checkout.rs`, `src/auth_capture.rs`, and `src/subscriptions.rs`. These modules mostly translate high-level methods into the correct bKash endpoint, base URL subdomain, and request shape. The differences between products are encoded here: for example, classic checkout and tokenized checkout share endpoint paths but differ in host and payment mode, while auth-capture uses some path parameters instead of body fields.

6. The request/response schema layer is under `src/models/`. It is divided by product and operation type (`checkout`, `tokenized`, `auth_capture`, `subscriptions`, plus `common` and `token`). This is where typed request bodies, response structs, and shared DTOs live, so the rest of the crate can stay strongly typed instead of dealing with raw JSON.

7. Error handling is a first-class subsystem in `src/error.rs`. The crate maps bKash’s status/error envelopes into a typed `Error` enum that distinguishes authentication failures, API errors, transport failures, timeouts, config problems, and JSON decoding issues. This lets callers separate retryable failures from auth/config problems without parsing response bodies themselves.

8. The operational flow for a typical API call is: user builds `Bkash` with credentials and environment; a product accessor constructs a request object; transport ensures a valid token exists; reqwest sends the HTTP request to the product-specific host and endpoint; the response is deserialized into a typed model; errors are normalized into `Error`. That is the core data path for all payment-related features.

9. Webhook support is isolated in `src/webhooks.rs` and is synchronous rather than network-client driven. It verifies SNS-style signatures, optionally fetches or uses an RSA public key, parses inbound webhook envelopes, and exposes typed event accessors. This is a separate inbound trust boundary from the outbound payment APIs.

10. Feature flags materially shape the compiled architecture. `tokenized-checkout` and `checkout` are enabled by default; `auth-capture`, `subscriptions`, and `webhooks` are optional. TLS is also split into mutually exclusive `rustls-tls` or `native-tls`. In diagram terms, the crate can be viewed as a shared core with optional product and security modules compiled in or out.

11. Testing is split between offline fixture-based integration tests and optional live sandbox smoke tests. `tests/transport_wiremock.rs` and the fixture directories validate request/response behavior against recorded JSON, while `tests/live/sandbox.rs` exercises real sandbox calls when explicitly run. This mirrors the architecture: local typed behavior is validated separately from the external bKash integration.

12. The examples in `examples/` are small orchestration drivers, not part of the library core. `quickstart.rs` demonstrates a single payment flow, and `from_env.rs` stages longer sandbox walkthroughs with manual wallet approval. They show the expected call sequencing across the same underlying client, transport, and model layers.

Main entry points: [`src/client.rs`](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/client.rs) (Bkash client), [`src/models/mod.rs`](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/mod.rs) (Models root), [`src/lib.rs`](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/lib.rs) (Crate API), [`src/transport.rs`](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/transport.rs) (Transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Shared core"]
  node_src_lib["Crate API<br/>[lib.rs]"]
  node_src_client["Bkash client<br/>shared client<br/>[client.rs]"]
  node_src_config["Config<br/>[config.rs]"]
  node_src_transport["Transport<br/>HTTP boundary<br/>[transport.rs]"]
  node_src_token(("Token cache<br/>auth cache<br/>[token.rs]"))
  node_src_error["Errors<br/>error model<br/>[error.rs]"]
  node_src_prelude["Prelude<br/>exports<br/>[prelude.rs]"]
end

subgraph group_products["Product facades"]
  node_src_checkout["Checkout<br/>product facade<br/>[checkout.rs]"]
  node_src_tokenized["Tokenized<br/>product facade<br/>[tokenized.rs]"]
  node_src_auth_capture["Auth capture<br/>product facade<br/>[auth_capture.rs]"]
  node_src_subscriptions["Subscriptions<br/>product facade<br/>[subscriptions.rs]"]
end

subgraph group_models["Typed models"]
  node_models_mod["Models root<br/>typed DTOs<br/>[mod.rs]"]
  node_models_common["Common DTOs<br/>shared models<br/>[common.rs]"]
  node_models_checkout["Checkout models<br/>product DTOs<br/>[mod.rs]"]
  node_models_tokenized["Tokenized models<br/>product DTOs<br/>[mod.rs]"]
  node_models_auth_capture["Auth capture DTOs<br/>product DTOs<br/>[auth_capture.rs]"]
  node_models_subscriptions["Subscription DTOs<br/>product DTOs<br/>[subscriptions.rs]"]
  node_models_token["Token DTOs<br/>auth models<br/>[token.rs]"]
end

subgraph group_trust["Inbound trust"]
  node_src_webhooks["Webhooks<br/>inbound verification<br/>[webhooks.rs]"]
end

subgraph group_demos["Examples"]
  node_examples_quickstart["Quickstart<br/>example<br/>[quickstart.rs]"]
  node_examples_from_env["From env<br/>example<br/>[from_env.rs]"]
end

node_src_lib -->|"exports"| node_src_client
node_src_lib -->|"exports"| node_src_config
node_src_lib -->|"exports"| node_src_error
node_src_lib -->|"exports"| node_src_prelude
node_src_client -->|"uses"| node_src_config
node_src_client -->|"owns"| node_src_transport
node_src_client -->|"shares"| node_src_token
node_src_client -->|"accessor"| node_src_checkout
node_src_client -->|"accessor"| node_src_tokenized
node_src_client -->|"accessor"| node_src_auth_capture
node_src_client -->|"accessor"| node_src_subscriptions
node_src_transport -->|"auths"| node_src_token
node_src_transport -->|"maps"| node_src_error
node_src_checkout -->|"serializes"| node_models_checkout
node_src_tokenized -->|"serializes"| node_models_tokenized
node_src_auth_capture -->|"serializes"| node_models_auth_capture
node_src_subscriptions -->|"serializes"| node_models_subscriptions
node_src_token -->|"serializes"| node_models_token
node_models_mod -->|"contains"| node_models_common
node_models_mod -->|"contains"| node_models_checkout
node_models_mod -->|"contains"| node_models_tokenized
node_models_mod -->|"contains"| node_models_auth_capture
node_models_mod -->|"contains"| node_models_subscriptions
node_models_mod -->|"contains"| node_models_token
node_src_webhooks -->|"maps"| node_src_error
node_src_webhooks -->|"parses"| node_models_common
node_examples_quickstart -->|"uses"| node_src_client
node_examples_from_env -->|"uses"| node_src_client

click node_src_lib "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/lib.rs"
click node_src_client "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/client.rs"
click node_src_config "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/config.rs"
click node_src_transport "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/transport.rs"
click node_src_token "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/token.rs"
click node_src_error "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/error.rs"
click node_src_prelude "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/prelude.rs"
click node_src_checkout "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/checkout.rs"
click node_src_tokenized "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/tokenized.rs"
click node_src_auth_capture "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/auth_capture.rs"
click node_src_subscriptions "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/subscriptions.rs"
click node_src_webhooks "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/webhooks.rs"
click node_models_mod "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/mod.rs"
click node_models_common "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/common.rs"
click node_models_checkout "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/checkout/mod.rs"
click node_models_tokenized "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/tokenized/mod.rs"
click node_models_auth_capture "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/auth_capture.rs"
click node_models_subscriptions "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/subscriptions.rs"
click node_models_token "https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/token.rs"
click node_examples_quickstart "https://github.com/dibakarsutradhar/bkash-rs/blob/main/examples/quickstart.rs"
click node_examples_from_env "https://github.com/dibakarsutradhar/bkash-rs/blob/main/examples/from_env.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_lib,node_src_client,node_src_config,node_src_transport,node_src_token,node_src_error,node_src_prelude toneBlue
class node_src_checkout,node_src_tokenized,node_src_auth_capture,node_src_subscriptions toneAmber
class node_models_mod,node_models_common,node_models_checkout,node_models_tokenized,node_models_auth_capture,node_models_subscriptions,node_models_token toneMint
class node_src_webhooks toneRose
class node_examples_quickstart,node_examples_from_env toneIndigo
```

## Components

### Shared core

Client, configuration, transport, auth, and errors that underpin all API flows.

- [Crate API](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/lib.rs): module · Public crate surface and re-exports. · `src/lib.rs`
- [Bkash client](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/client.rs): shared client · Cheaply cloneable handle that owns shared runtime state and exposes product accessors. · `src/client.rs`
- [Config](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/config.rs): runtime config · Validates credentials, environment, timeout, retries, base URL, and optional HTTP client. · `src/config.rs`
- [Transport](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/transport.rs): HTTP boundary · Reqwest-backed outbound transport with timeout, retry, and auth attachment behavior. · `src/transport.rs`
- [Token cache](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/token.rs): auth cache · Access-token acquisition and refresh shared across all product flows. · `src/token.rs`
- [Errors](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/error.rs): error model · Typed crate error mapping for auth, API, transport, config, timeout, and decode failures. · `src/error.rs`
- [Prelude](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/prelude.rs): exports · Convenience imports for downstream consumers. · `src/prelude.rs`

### Product facades

Feature-gated outbound APIs for the different bKash product families.

- [Checkout](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/checkout.rs): product facade · Classic checkout API facade for payment and refund flows. · `src/checkout.rs`
- [Tokenized](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/tokenized.rs): product facade · Tokenized checkout, agreement, payment, refund, and search facade. · `src/tokenized.rs`
- [Auth capture](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/auth_capture.rs): product facade · Auth-capture API facade with its product-specific request shaping. · `src/auth_capture.rs`
- [Subscriptions](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/subscriptions.rs): product facade · Subscription lifecycle facade for recurring payment features. · `src/subscriptions.rs`

### Typed models

Request and response DTOs organized by product and operation.

- [Models root](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/mod.rs): typed DTOs · Top-level model namespace for requests and responses. · `src/models/mod.rs`
- [Common DTOs](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/common.rs): shared models · Shared response envelope and cross-product data structures. · `src/models/common.rs`
- [Checkout models](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/checkout/mod.rs): product DTOs · Typed checkout payment, refund, and search structures. · `src/models/checkout/mod.rs`
- [Tokenized models](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/tokenized/mod.rs): product DTOs · Typed tokenized agreement, payment, refund, and search structures. · `src/models/tokenized/mod.rs`
- [Auth capture DTOs](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/auth_capture.rs): product DTOs · Typed auth-capture request and response structures. · `src/models/auth_capture.rs`
- [Subscription DTOs](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/subscriptions.rs): product DTOs · Typed subscription request and response structures. · `src/models/subscriptions.rs`
- [Token DTOs](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/models/token.rs): auth models · Typed token request and response structures. · `src/models/token.rs`

### Inbound trust

Webhook verification and parsing for inbound events.

- [Webhooks](https://github.com/dibakarsutradhar/bkash-rs/blob/main/src/webhooks.rs): inbound verification · Synchronous webhook parsing and signature verification boundary. · `src/webhooks.rs`

### Examples

Small orchestration programs showing end-to-end usage.

- [Quickstart](https://github.com/dibakarsutradhar/bkash-rs/blob/main/examples/quickstart.rs): example · Minimal end-to-end payment walkthrough. · `examples/quickstart.rs`
- [From env](https://github.com/dibakarsutradhar/bkash-rs/blob/main/examples/from_env.rs): example · Longer sandbox walkthrough using environment-driven setup. · `examples/from_env.rs`

## Connections

- Crate API → Bkash client: exports · Public crate API centers on the shared client handle.
- Crate API → Config: exports · Configuration types are part of the public surface.
- Crate API → Errors: exports · Typed error handling is exposed to consumers.
- Crate API → Prelude: exports · Convenience import path for downstream users.
- Bkash client → Config: uses · Client construction consumes validated runtime config.
- Bkash client → Transport: owns · Client delegates outbound requests through shared transport.
- Bkash client → Token cache: shares · Client shares token state across product facades.
- Bkash client → Checkout: accessor · Client exposes checkout facade.
- Bkash client → Tokenized: accessor · Client exposes tokenized facade.
- Bkash client → Auth capture: accessor · Client exposes auth-capture facade.
- Bkash client → Subscriptions: accessor · Client exposes subscriptions facade.
- Transport → Token cache: auths · Transport ensures a valid access token before requests.
- Transport → Errors: maps · Transport surfaces network and timeout failures as typed errors.
- Checkout → Checkout models: serializes · Checkout facade builds and decodes checkout-specific DTOs.
- Tokenized → Tokenized models: serializes · Tokenized facade builds and decodes tokenized DTOs.
- Auth capture → Auth capture DTOs: serializes · Auth-capture facade uses its dedicated model set.
- Subscriptions → Subscription DTOs: serializes · Subscriptions facade uses its dedicated model set.
- Token cache → Token DTOs: serializes · Token acquisition uses token request and response DTOs.
- Models root → Common DTOs: contains · Shared DTOs live under the model root.
- Models root → Checkout models: contains · Checkout models are grouped under the model root.
- Models root → Tokenized models: contains · Tokenized models are grouped under the model root.
- Models root → Auth capture DTOs: contains · Auth-capture models are grouped under the model root.
- Models root → Subscription DTOs: contains · Subscription models are grouped under the model root.
- Models root → Token DTOs: contains · Token models are grouped under the model root.
- Webhooks → Errors: maps · Webhook verification and parsing surface typed failures.
- Webhooks → Common DTOs: parses · Webhook envelopes reuse shared DTOs.
- Quickstart → Bkash client: uses · Example drives the shared client and product facades.
- From env → Bkash client: uses · Example demonstrates environment-based client setup.