# oj-washingtone/tranxs architecture

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

- Interactive diagram: https://gitdiagram.com/oj-washingtone/tranxs
- Repository: https://github.com/oj-washingtone/tranxs

## Overview

##### Project type and purpose
- Tranxs is an open-source SDK (npm package) that wraps the Safaricom Daraja M-Pesa APIs.
- Its goal is to simplify all major M-Pesa transactions (STK Push, B2C, B2B, C2B, Reversal, Account Balance, Transaction Status) for JavaScript/TypeScript applications.

##### File structure
Top level
- src/index.ts           – public entrypoint, exports hooks & classes
- src/mpesa/             – core M-Pesa logic
– Mpesa.ts           • main class for initializing credentials & environment
– segGen.ts          • security signature generator (timestamp, nonce)
– cert.cer           • TLS certificate for client authentication
- src/types/             – TypeScript definitions for various M-Pesa payloads
- src/utils/             – helper functions (cleanPhone.ts, generateTimeStamp.ts)
Config files
- package.json, tsconfig.json, .github/workflows/npm-publish.yml

##### Elements
- Callback endpoints as external nodes receiving POSTs from the API
– Blue for SDK internal modules
– Green for client application elements
– Orange for external services (Daraja API, callback endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application
    ClientApp["Client Application"]:::client

    %% SDK Layer
    subgraph "Tranxs SDK"
        direction TB
        Entry["Entrypoint\n(useMpesa / Mpesa class)"]:::sdk
        Auth["OAuth Token Manager"]:::sdk
        Sig["Signature Generator\n(segGen.ts)"]:::sdk
        Http["HTTP Client\n(Daraja API Calls)"]:::sdk
        subgraph "Supporting Modules"
            direction TB
            Utils["Utilities"]:::sdk
            Types["Type Definitions"]:::sdk
        end
        Cert["TLS Certificate\n(cert.cer)"]:::sdk
    end

    %% External Services
    subgraph "Safaricom Daraja API"
        direction TB
        OAuthEP["/oauth/v1/generate?grant_type=client_credentials"]:::external
        TransEP["/stkpush/v1/processrequest\n/B2C\n/B2B\n/C2B\n/Reversal\n/AccountBalance\n/TransactionStatus"]:::external
    end

    subgraph "Callback Endpoints"
        direction TB
        ValCB["Validation URL"]:::external
        ConfCB["Confirmation URL"]:::external
        ResultCB["resultCallbackUrl"]:::external
        TimeoutCB["timeout URL"]:::external
    end

    %% Data Flow
    ClientApp -->|1. init & inject creds/URLs| Entry
    Entry -->|2. request token| Auth
    Auth -->|uses cert & signature| Cert
    Cert -->|certificate| Auth
    Auth -->|3. GET token| OAuthEP
    OAuthEP -->|token| Auth
    Entry -->|sign request| Sig
    Sig -->|signature| Http
    Auth -->|token| Http
    Http -->|4. send signed request| TransEP
    TransEP -->|sync response| Http
    Http -->|response| Entry
    TransEP -->|5. async POST| ValCB
    TransEP -->|5. async POST| ConfCB
    TransEP -->|5. async POST| ResultCB
    TransEP -->|5. async POST| TimeoutCB
    ValCB -->|callback payload| Entry
    ConfCB -->|callback payload| Entry
    ResultCB -->|callback payload| Entry
    TimeoutCB -->|callback payload| Entry

    %% Click Events
    click Entry "https://github.com/oj-washingtone/tranxs/blob/main/src/index.ts"
    click Auth "https://github.com/oj-washingtone/tranxs/blob/main/src/mpesa/Mpesa.ts"
    click Sig "https://github.com/oj-washingtone/tranxs/blob/main/src/mpesa/segGen.ts"
    click Cert "https://github.com/oj-washingtone/tranxs/blob/main/src/mpesa/cert.cer"
    click Utils "https://github.com/oj-washingtone/tranxs/blob/main/src/utils/cleanPhone.ts"
    click Utils "https://github.com/oj-washingtone/tranxs/blob/main/src/utils/generateTimeStamp.ts"
    click Types "https://github.com/oj-washingtone/tranxs/blob/main/src/types/common.ts"
    click Types "https://github.com/oj-washingtone/tranxs/blob/main/src/types/airtel.types.ts"
    click Types "https://github.com/oj-washingtone/tranxs/blob/main/src/types/mepesa.types.ts"

    %% Styles
    classDef sdk fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef client fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#333,stroke-width:1px
```
