# generalbytescom/batm_public architecture

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

- Interactive diagram: https://gitdiagram.com/generalbytescom/batm_public
- Repository: https://github.com/generalbytescom/batm_public

## Overview

This repository is an open extension ecosystem for General Bytes Bitcoin ATM products, especially BATM Server (CAS), rather than the CAS runtime itself. The principal workflow is an operator or developer implementing an extension against the published API, packaging it for CAS to discover, and exposing a capability such as a wallet, exchange, rate source, payment processor, compliance provider, or REST service. The tree also includes reference integrations, a sample operator sell website, a verification helper, and an SSH tunnel. Relationships among unsampled subsystems are limited to documented capabilities; the diagram does not imply unseen runtime wiring.

Main entry points: [`verification_site/src/main/java/com/generalbytes/verification/controller/VerificationController.java`](https://github.com/generalbytescom/batm_public/blob/master/verification_site/src/main/java/com/generalbytes/verification/controller/VerificationController.java) (Verification endpoints), [`server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExtension.java`](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExtension.java) (Extension contract), [`server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExtensionContext.java`](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExtensionContext.java) (CAS context), [`server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IRestService.java`](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IRestService.java) (REST service API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Extension API"]
  node_extension_contract["Extension contract<br/>[IExtension.java]"]
  node_extension_context["CAS context"]
  node_wallet_api["Wallet API<br/>[IWallet.java]"]
  node_exchange_api["Exchange API<br/>[IExchange.java]"]
  node_rates_api["Rate source API<br/>[IRateSource.java]"]
  node_payment_api["Payment processor API"]
  node_compliance_api["AML and watchlists<br/>[IAMLProvider.java]"]
  node_rest_api["REST service API<br/>[IRestService.java]"]
  node_event_api["Transaction listeners"]
end

subgraph group_integrations["Reference Integrations"]
  node_extra_extensions["Reference extensions"]
  node_travel_rule["Travel rule providers<br/>[SumsubService.java]"]
  node_lightning_lnurl["Lightning LNURL"]
  node_veriff_webhook["Veriff webhook"]
end

subgraph group_operator["Operator Services"]
  node_sell_website["Operator sell website<br/>[SellController.php]"]
  node_terminals_client["CAS terminal client<br/>[Terminals.php]"]
end

subgraph group_support["Supporting Services"]
  node_verification_controller["Verification endpoints"]
  node_applicant_cache[("Applicant token cache")]
  node_ssh_tunnel["SSH tunnel<br/>[Main.java]"]
end

node_operator_dev(("Operator developer"))
node_cas["BATM Server CAS"]

node_operator_dev -->|"implements"| node_extension_contract
node_extension_contract -->|"receives on init"| node_extension_context
node_cas -->|"discovers extensions"| node_extension_contract
node_operator_dev -->|"implements"| node_wallet_api
node_operator_dev -->|"implements"| node_exchange_api
node_operator_dev -->|"implements"| node_rates_api
node_operator_dev -->|"implements"| node_payment_api
node_operator_dev -->|"implements"| node_compliance_api
node_operator_dev -->|"implements"| node_rest_api
node_operator_dev -->|"implements"| node_event_api
node_extra_extensions -->|"demonstrates"| node_wallet_api
node_extra_extensions -->|"demonstrates"| node_exchange_api
node_travel_rule -->|"uses"| node_extension_context
node_lightning_lnurl -->|"uses"| node_extension_context
node_lightning_lnurl -->|"implements"| node_rest_api
node_veriff_webhook -->|"implements"| node_rest_api
node_sell_website -->|"requests terminals"| node_terminals_client
node_terminals_client -.->|"calls CAS services"| node_cas
node_cas -->|"registers applicant"| node_verification_controller
node_verification_controller -->|"stores and retrieves"| node_applicant_cache
node_verification_controller -->|"submits check"| node_cas

click node_extension_contract "https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExtension.java"
click node_extension_context "https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExtensionContext.java"
click node_wallet_api "https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IWallet.java"
click node_exchange_api "https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExchange.java"
click node_rates_api "https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IRateSource.java"
click node_payment_api "https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IPaymentProcessor.java"
click node_compliance_api "https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/aml/IAMLProvider.java"
click node_rest_api "https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IRestService.java"
click node_event_api "https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/ITransactionListener.java"
click node_extra_extensions "https://github.com/generalbytescom/batm_public/tree/master/server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/extra"
click node_travel_rule "https://github.com/generalbytescom/batm_public/blob/master/server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/travelrule/sumsub/SumsubService.java"
click node_lightning_lnurl "https://github.com/generalbytescom/batm_public/blob/master/server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/extra/lightningbitcoin/lnurl/LnurlRestService.java"
click node_veriff_webhook "https://github.com/generalbytescom/batm_public/blob/master/server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/extra/identityverification/veriff/VeriffRestService.java"
click node_sell_website "https://github.com/generalbytescom/batm_public/blob/master/operators_sample_website/website/app/Http/Controllers/SellController.php"
click node_terminals_client "https://github.com/generalbytescom/batm_public/blob/master/operators_sample_website/website/app/GBlib/Terminals.php"
click node_verification_controller "https://github.com/generalbytescom/batm_public/blob/master/verification_site/src/main/java/com/generalbytes/verification/controller/VerificationController.java"
click node_applicant_cache "https://github.com/generalbytescom/batm_public/blob/master/verification_site/src/main/java/com/generalbytes/verification/service/ApplicantService.java"
click node_ssh_tunnel "https://github.com/generalbytescom/batm_public/blob/master/batm_ssh_tunnel/src/main/java/com/generalbytes/batm/sshtunnel/Main.java"

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_extension_contract,node_extension_context,node_wallet_api,node_exchange_api,node_rates_api,node_payment_api,node_compliance_api,node_rest_api,node_event_api toneBlue
class node_extra_extensions,node_travel_rule,node_lightning_lnurl,node_veriff_webhook toneAmber
class node_sell_website,node_terminals_client,node_cas toneMint
class node_verification_controller,node_applicant_cache,node_ssh_tunnel toneRose
class node_operator_dev toneIndigo
```

## Components

### Extension API

- [Extension contract](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExtension.java): `server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExtension.java`
- [CAS context](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExtensionContext.java): `server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExtensionContext.java`
- [Wallet API](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IWallet.java): `server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IWallet.java`
- [Exchange API](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExchange.java): `server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IExchange.java`
- [Rate source API](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IRateSource.java): `server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IRateSource.java`
- [Payment processor API](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IPaymentProcessor.java): `server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IPaymentProcessor.java`
- [AML and watchlists](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/aml/IAMLProvider.java): `server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/aml/IAMLProvider.java`
- [REST service API](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IRestService.java): `server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IRestService.java`
- [Transaction listeners](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/ITransactionListener.java): `server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/ITransactionListener.java`

### Reference Integrations

- [Reference extensions](https://github.com/generalbytescom/batm_public/tree/master/server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/extra): `server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/extra`
- [Travel rule providers](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/travelrule/sumsub/SumsubService.java): `server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/travelrule/sumsub/SumsubService.java`
- [Lightning LNURL](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/extra/lightningbitcoin/lnurl/LnurlRestService.java): `server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/extra/lightningbitcoin/lnurl/LnurlRestService.java`
- [Veriff webhook](https://github.com/generalbytescom/batm_public/blob/master/server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/extra/identityverification/veriff/VeriffRestService.java): `server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/extra/identityverification/veriff/VeriffRestService.java`

### Operator Services

- [Operator sell website](https://github.com/generalbytescom/batm_public/blob/master/operators_sample_website/website/app/Http/Controllers/SellController.php): `operators_sample_website/website/app/Http/Controllers/SellController.php`
- [CAS terminal client](https://github.com/generalbytescom/batm_public/blob/master/operators_sample_website/website/app/GBlib/Terminals.php): `operators_sample_website/website/app/GBlib/Terminals.php`

### Supporting Services

- [Verification endpoints](https://github.com/generalbytescom/batm_public/blob/master/verification_site/src/main/java/com/generalbytes/verification/controller/VerificationController.java): `verification_site/src/main/java/com/generalbytes/verification/controller/VerificationController.java`
- [Applicant token cache](https://github.com/generalbytescom/batm_public/blob/master/verification_site/src/main/java/com/generalbytes/verification/service/ApplicantService.java): `verification_site/src/main/java/com/generalbytes/verification/service/ApplicantService.java`
- [SSH tunnel](https://github.com/generalbytescom/batm_public/blob/master/batm_ssh_tunnel/src/main/java/com/generalbytes/batm/sshtunnel/Main.java): `batm_ssh_tunnel/src/main/java/com/generalbytes/batm/sshtunnel/Main.java`

### Other components

- **Operator developer**
- **BATM Server CAS**

## Connections

- Operator developer → Extension contract: implements (evidence: `README.md`)
- Extension contract → CAS context: receives on init (evidence: `README.md`)
- BATM Server CAS → Extension contract: discovers extensions (evidence: `README.md`)
- Operator developer → Wallet API: implements (evidence: `README.md`)
- Operator developer → Exchange API: implements (evidence: `README.md`)
- Operator developer → Rate source API: implements (evidence: `README.md`)
- Operator developer → Payment processor API: implements (evidence: `README.md`)
- Operator developer → AML and watchlists: implements (evidence: `README.md`)
- Operator developer → REST service API: implements (evidence: `README.md`)
- Operator developer → Transaction listeners: implements (evidence: `README.md`)
- Reference extensions → Wallet API: demonstrates (evidence: `README.md`)
- Reference extensions → Exchange API: demonstrates (evidence: `README.md`)
- Travel rule providers → CAS context: uses (evidence: `server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/travelrule/sumsub/SumsubService.java`)
- Lightning LNURL → CAS context: uses (evidence: `server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/extra/lightningbitcoin/lnurl/LnurlRestService.java`)
- Lightning LNURL → REST service API: implements (evidence: `server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/extra/lightningbitcoin/lnurl/LnurlRestService.java`)
- Veriff webhook → REST service API: implements (evidence: `server_extensions_extra/src/main/java/com/generalbytes/batm/server/extensions/extra/identityverification/veriff/VeriffRestService.java`)
- Operator sell website → CAS terminal client: requests terminals (evidence: `operators_sample_website/website/app/Http/Controllers/SellController.php`)
- CAS terminal client → BATM Server CAS: calls CAS services
- BATM Server CAS → Verification endpoints: registers applicant (evidence: `verification_site/src/main/java/com/generalbytes/verification/controller/VerificationController.java`)
- Verification endpoints → Applicant token cache: stores and retrieves (evidence: `verification_site/src/main/java/com/generalbytes/verification/controller/VerificationController.java`)
- Verification endpoints → BATM Server CAS: submits check (evidence: `verification_site/src/main/java/com/generalbytes/verification/controller/VerificationController.java`)
