# hirotomasato/scbz architecture

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

- Interactive diagram: https://gitdiagram.com/hirotomasato/scbz
- Repository: https://github.com/hirotomasato/scbz

## Overview

scbz provides both a Go SDK and a REST gateway for SociaBuzz donations. The gateway workflow is fee estimation (optional), donation submission and session retention, payment-method listing, payment creation, then status checks; the SDK exposes the corresponding donation and payment operations directly. A separate webhook dispatcher polls persisted payments and sends terminal events to callback URLs. The graph follows documented routes and excerpted calls; some lower-level SDK request details and the webhook’s startup wiring are only partially shown.

Main entry points: [`sociabuzz/client.go`](https://github.com/hirotomasato/scbz/blob/main/sociabuzz/client.go) (Donation workflow), [`cmd/scbz-server/main.go`](https://github.com/hirotomasato/scbz/blob/main/cmd/scbz-server/main.go) (HTTP router), [`server/routes/donate.go`](https://github.com/hirotomasato/scbz/blob/main/server/routes/donate.go) (Donation endpoint), [`server/routes/fees.go`](https://github.com/hirotomasato/scbz/blob/main/server/routes/fees.go) (Fee endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["REST gateway"]
  node_router["HTTP router<br/>[main.go]"]
  node_settings["Settings<br/>[config.go]"]
  node_auth["API authentication<br/>[auth.go]"]
  node_api_schemas["API schemas<br/>[schemas.go]"]
  node_donate_route["Donation endpoint<br/>[donate.go]"]
  node_fee_route["Fee endpoints<br/>[fees.go]"]
  node_payment_route["Payment endpoints<br/>[payment.go]"]
end

subgraph group_sdk["Donation SDK"]
  node_donation_sdk["Donation workflow<br/>[client.go]"]
  node_fee_sdk["Fee estimator<br/>[fees.go]"]
  node_http_client["SociaBuzz transport<br/>[http.go]"]
  node_countries["Country catalog<br/>[constants.go]"]
  node_sdk_models["SDK data models<br/>[models.go]"]
  node_sdk_errors["SDK errors<br/>[errors.go]"]
  node_sdk_json["JSON helpers<br/>[json.go]"]
end

subgraph group_state["Sessions and callbacks"]
  node_sessions[("Session store<br/>[session.go]")]
  node_webhooks["Webhook poller<br/>[webhook.go]"]
end

node_api_user(("API client"))
node_sdk_user(("SDK caller"))
node_callback(("Callback receiver"))
node_sociabuzz{{"SociaBuzz service"}}

node_api_user -->|"sends requests"| node_router
node_router -->|"applies middleware"| node_auth
node_router -->|"loads settings"| node_settings
node_router -->|"routes donation"| node_donate_route
node_router -->|"routes fees"| node_fee_route
node_router -->|"routes payments"| node_payment_route
node_donate_route -->|"decodes and returns"| node_api_schemas
node_fee_route -->|"decodes and returns"| node_api_schemas
node_payment_route -->|"decodes and returns"| node_api_schemas
node_donate_route -->|"submits donation"| node_donation_sdk
node_fee_route -->|"estimates fees"| node_fee_sdk
node_fee_route -->|"lists countries"| node_countries
node_payment_route -->|"loads and updates"| node_sessions
node_donate_route -->|"stores session"| node_sessions
node_payment_route -->|"requests payment actions"| node_donation_sdk
node_donation_sdk -->|"delegates requests"| node_http_client
node_fee_sdk -->|"delegates requests"| node_http_client
node_donation_sdk -->|"validates country"| node_countries
node_fee_sdk -->|"selects currency"| node_countries
node_http_client -->|"calls service"| node_sociabuzz
node_sdk_user -->|"starts donation flow"| node_donation_sdk
node_sdk_user -->|"requests estimate"| node_fee_sdk
node_sessions -->|"restores donation"| node_donation_sdk
node_webhooks -->|"loads pending sessions"| node_sessions
node_webhooks -->|"checks payment status"| node_donation_sdk
node_webhooks -->|"posts terminal event"| node_callback
node_donation_sdk -.->|"uses data types"| node_sdk_models
node_donation_sdk -.->|"returns typed errors"| node_sdk_errors
node_http_client -.->|"parses responses"| node_sdk_json

click node_router "https://github.com/hirotomasato/scbz/blob/main/cmd/scbz-server/main.go"
click node_settings "https://github.com/hirotomasato/scbz/blob/main/server/config.go"
click node_auth "https://github.com/hirotomasato/scbz/blob/main/server/auth.go"
click node_api_schemas "https://github.com/hirotomasato/scbz/blob/main/server/schemas.go"
click node_donate_route "https://github.com/hirotomasato/scbz/blob/main/server/routes/donate.go"
click node_fee_route "https://github.com/hirotomasato/scbz/blob/main/server/routes/fees.go"
click node_payment_route "https://github.com/hirotomasato/scbz/blob/main/server/routes/payment.go"
click node_sessions "https://github.com/hirotomasato/scbz/blob/main/server/session.go"
click node_webhooks "https://github.com/hirotomasato/scbz/blob/main/server/webhook.go"
click node_donation_sdk "https://github.com/hirotomasato/scbz/blob/main/sociabuzz/client.go"
click node_fee_sdk "https://github.com/hirotomasato/scbz/blob/main/sociabuzz/fees.go"
click node_http_client "https://github.com/hirotomasato/scbz/blob/main/sociabuzz/http.go"
click node_countries "https://github.com/hirotomasato/scbz/blob/main/sociabuzz/constants.go"
click node_sdk_models "https://github.com/hirotomasato/scbz/blob/main/sociabuzz/models.go"
click node_sdk_errors "https://github.com/hirotomasato/scbz/blob/main/sociabuzz/errors.go"
click node_sdk_json "https://github.com/hirotomasato/scbz/blob/main/sociabuzz/json.go"

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_router,node_settings,node_auth,node_api_schemas,node_donate_route,node_fee_route,node_payment_route,node_api_user toneBlue
class node_donation_sdk,node_fee_sdk,node_http_client,node_countries,node_sdk_models,node_sdk_errors,node_sdk_json toneAmber
class node_sessions,node_webhooks toneMint
class node_sdk_user,node_callback,node_sociabuzz toneIndigo
```

## Components

### REST gateway

- [HTTP router](https://github.com/hirotomasato/scbz/blob/main/cmd/scbz-server/main.go): `cmd/scbz-server/main.go`
- [Settings](https://github.com/hirotomasato/scbz/blob/main/server/config.go): `server/config.go`
- [API authentication](https://github.com/hirotomasato/scbz/blob/main/server/auth.go): `server/auth.go`
- [API schemas](https://github.com/hirotomasato/scbz/blob/main/server/schemas.go): `server/schemas.go`
- [Donation endpoint](https://github.com/hirotomasato/scbz/blob/main/server/routes/donate.go): `server/routes/donate.go`
- [Fee endpoints](https://github.com/hirotomasato/scbz/blob/main/server/routes/fees.go): `server/routes/fees.go`
- [Payment endpoints](https://github.com/hirotomasato/scbz/blob/main/server/routes/payment.go): `server/routes/payment.go`

### Donation SDK

- [Donation workflow](https://github.com/hirotomasato/scbz/blob/main/sociabuzz/client.go): `sociabuzz/client.go`
- [Fee estimator](https://github.com/hirotomasato/scbz/blob/main/sociabuzz/fees.go): `sociabuzz/fees.go`
- [SociaBuzz transport](https://github.com/hirotomasato/scbz/blob/main/sociabuzz/http.go): `sociabuzz/http.go`
- [Country catalog](https://github.com/hirotomasato/scbz/blob/main/sociabuzz/constants.go): `sociabuzz/constants.go`
- [SDK data models](https://github.com/hirotomasato/scbz/blob/main/sociabuzz/models.go): `sociabuzz/models.go`
- [SDK errors](https://github.com/hirotomasato/scbz/blob/main/sociabuzz/errors.go): `sociabuzz/errors.go`
- [JSON helpers](https://github.com/hirotomasato/scbz/blob/main/sociabuzz/json.go): `sociabuzz/json.go`

### Sessions and callbacks

- [Session store](https://github.com/hirotomasato/scbz/blob/main/server/session.go): `server/session.go`
- [Webhook poller](https://github.com/hirotomasato/scbz/blob/main/server/webhook.go): `server/webhook.go`

### Other components

- **API client**
- **SDK caller**
- **Callback receiver**
- **SociaBuzz service**

## Connections

- API client → HTTP router: sends requests (evidence: `README.md`)
- HTTP router → API authentication: applies middleware (evidence: `cmd/scbz-server/main.go`)
- HTTP router → Settings: loads settings (evidence: `cmd/scbz-server/main.go`)
- HTTP router → Donation endpoint: routes donation (evidence: `cmd/scbz-server/main.go`)
- HTTP router → Fee endpoints: routes fees (evidence: `cmd/scbz-server/main.go`)
- HTTP router → Payment endpoints: routes payments (evidence: `cmd/scbz-server/main.go`)
- Donation endpoint → API schemas: decodes and returns (evidence: `server/routes/donate.go`)
- Fee endpoints → API schemas: decodes and returns (evidence: `server/routes/fees.go`)
- Payment endpoints → API schemas: decodes and returns (evidence: `server/routes/payment.go`)
- Donation endpoint → Donation workflow: submits donation (evidence: `server/routes/donate.go`)
- Fee endpoints → Fee estimator: estimates fees (evidence: `server/routes/fees.go`)
- Fee endpoints → Country catalog: lists countries (evidence: `server/routes/fees.go`)
- Payment endpoints → Session store: loads and updates (evidence: `server/routes/payment.go`)
- Donation endpoint → Session store: stores session (evidence: `server/routes/donate.go`)
- Payment endpoints → Donation workflow: requests payment actions (evidence: `server/routes/payment.go`)
- Donation workflow → SociaBuzz transport: delegates requests (evidence: `sociabuzz/client.go`)
- Fee estimator → SociaBuzz transport: delegates requests (evidence: `sociabuzz/fees.go`)
- Donation workflow → Country catalog: validates country (evidence: `sociabuzz/client.go`)
- Fee estimator → Country catalog: selects currency (evidence: `sociabuzz/fees.go`)
- SociaBuzz transport → SociaBuzz service: calls service (evidence: `README.md`)
- SDK caller → Donation workflow: starts donation flow (evidence: `README.md`)
- SDK caller → Fee estimator: requests estimate (evidence: `README.md`)
- Session store → Donation workflow: restores donation (evidence: `server/session.go`)
- Webhook poller → Session store: loads pending sessions (evidence: `server/webhook.go`)
- Webhook poller → Donation workflow: checks payment status (evidence: `server/webhook.go`)
- Webhook poller → Callback receiver: posts terminal event (evidence: `server/webhook.go`)
- Donation workflow → SDK data models: uses data types
- Donation workflow → SDK errors: returns typed errors
- SociaBuzz transport → JSON helpers: parses responses
