# firecoinjp/huobi-japan-api-samples architecture

> Architecture diagram of the GitHub repository firecoinjp/huobi-japan-api-samples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/firecoinjp/huobi-japan-api-samples
- Repository: https://github.com/firecoinjp/huobi-japan-api-samples

## Overview

##### Project Type and Purpose
- This project is a sample API client written in Go that demonstrates how to interact with the Huobi Japan (Bittrade) API. It is used to test and validate a variety of trading-related commands (both REST and WebSocket) such as account balance, placing orders, retrieving market data (kline, tickers, depth), and more.
- The application runs in a command-line “subcommand mode,” where each command (located in the “cmds” folder) implements a particular API interaction or feature.
- Key functionality includes user authentication (signature generation using HmacSHA256), REST API calls, and WebSocket communication.

##### Analysis of the File Structure and Key Components
- Top-Level Files and Directories:
- main.go: The entry point that initializes the application.
- cmds/: Contains various Go files where each file implements a subcommand (e.g., “accounts.go”, “kline.go”, “order.go”). This represents the command layer.
- core/: Holds the core libraries:
· core/api/http.go: Implements REST API client logic and authentication signing.
· core/ws/websocket.go: Implements WebSocket client logic and signature handling.
· core/crypto/: Provides the cryptographic functions used for authentication.
- config/: Contains configuration code (with a sample YAML file provided at the root as config.yaml.sample) that guides the runtime behavior.
- data/: Defines data structures for request payloads (a useful abstraction between subcommands and API calls).
- json/: Contains sample or output data in JSON format, which can be used for testing or as a reference for response structures.
- Makefile & .gitignore: Build scripts and ignored files for version control.
- The organization clearly separates concerns: command handling, core logic (networking and authentication), configurations, and sample data.

a. Main Components:
- Entry Point (main.go)
- Command Layer (“cmds”): Represents the different API operations like accounts, balance, order, kline, etc.
- Core API Layer (“core”):
- REST API Client (core/api/http.go): Handles HTTP request preparation, signing, and sending.
- WebSocket Client (core/ws/websocket.go): Handles WS connections, signing, and message communication.
- Crypto Module (core/crypto): Supports signature generation.
- Configuration (config & config.yaml): Contains API keys, host, and other runtime settings.
- Data Abstraction (data/): Contains request structure definitions used by the commands.
- Persistence/Output (json/): Provides sample responses and output saving if enabled.
- External Systems: Huobi Japan (Bittrade) API endpoints.

b. Relationships and Interactions:
- The system begins at the main entry point (main.go) which loads configuration settings.
- The “cmds” folder encapsulates subcommands that the user invokes. Each subcommand calls functions in the core API layer.
- The core API layer is divided into the REST API Client and WebSocket Client. These components handle authentication (using code from core/crypto) and connect to external endpoints.
- Data structures defined in the “data” folder are used to build request payloads passed between “cmds” and “core.”
- The output (and potentially the logging of responses) interacts with the “json” directory.
- The communication with external systems is shown as outbound interactions coming from the REST and WebSocket components.

c. Architectural Patterns and Important Design Principles:
- Separation of Concerns: There is a clear division between CLI (cmds) and the underlying libraries (core) supporting external API communications.
- Modularity: Each subcommand encapsulates its own functionality, and helper packages (like crypto and data) are reused across the system.
- Extensibility: The design allows adding new subcommands (for other API operations) and easily swapping out or enhancing parts of the API client logic.
- Statelessness in API calls: Each command call prepares its own authentication parameters and sends independent requests.

d. Including Relevant Technologies:
- Language: Go
- Frameworks/Libraries: Standard Go libraries for HTTP and JSON, Gorilla Websocket (or similar) given the websocket usage.
- External API: Huobi Japan API endpoints via REST and WebSocket protocols.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Initialization Layer
    subgraph "Initialization"
        A["Main Entry Point – main.go"]:::entry
        B["Configuration – config.yaml & config/"]:::config
        A -->|"loads"| B
    end

    %% Command Layer
    subgraph "Command Layer"
        C["Command Handlers – cmds/"]:::cmd
        D["Data Structures – data/"]:::data
        C -->|"builds_requests"| D
    end

    %% Core API Layer
    subgraph "Core API Layer"
        E["REST API Client – core/api/http.go"]:::api
        F["WebSocket Client – core/ws/websocket.go"]:::api
        G["Cryptographic Functions – core/crypto/"]:::crypto
        C -->|"invokes"| E
        C -->|"invokes"| F
        E -->|"uses"| G
        F -->|"uses"| G
    end

    %% External API Interaction
    H["External API Endpoints – Bittrade"]:::external

    %% Output & Sample Data
    subgraph "Output & Samples"
        I["JSON Samples – json/"]:::sample
    end

    %% Connections for Core API Communication
    E -->|"sends_requests"| H
    F -->|"sends_messages"| H
    C -->|"outputs_response"| I
    B -->|"initializes_app"| C

    %% Click Events
    click A "https://github.com/firecoinjp/huobi-japan-api-samples/blob/master/main.go"
    click B "https://github.com/firecoinjp/huobi-japan-api-samples/tree/master/config/"
    click C "https://github.com/firecoinjp/huobi-japan-api-samples/tree/master/cmds/"
    click D "https://github.com/firecoinjp/huobi-japan-api-samples/tree/master/data/"
    click E "https://github.com/firecoinjp/huobi-japan-api-samples/blob/master/core/api/http.go"
    click F "https://github.com/firecoinjp/huobi-japan-api-samples/blob/master/core/ws/websocket.go"
    click G "https://github.com/firecoinjp/huobi-japan-api-samples/tree/master/core/crypto/"
    click I "https://github.com/firecoinjp/huobi-japan-api-samples/tree/master/json/"

    %% Styling Classes
    classDef entry fill:#f9f,stroke:#333,stroke-width:2px,color:#000;
    classDef config fill:#f96,stroke:#333,stroke-width:2px,color:#000;
    classDef cmd fill:#9f9,stroke:#333,stroke-width:2px,color:#000;
    classDef api fill:#99f,stroke:#333,stroke-width:2px,color:#000;
    classDef crypto fill:#ff9,stroke:#333,stroke-width:2px,color:#000;
    classDef data fill:#fc9,stroke:#333,stroke-width:2px,color:#000;
    classDef external fill:#f66,stroke:#333,stroke-width:2px,color:#000;
    classDef sample fill:#6f6,stroke:#333,stroke-width:2px,color:#000;
```
