# tnar/coincheck-rust architecture

> Architecture diagram of the GitHub repository tnar/coincheck-rust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tnar/coincheck-rust
- Repository: https://github.com/tnar/coincheck-rust

## Overview

##### Main Components
From the file tree and README, split the system into these top-level building blocks:
- Configuration Loader (src/config.rs)
- Runtime & Orchestration (src/main.rs + Tokio)
- WebSocket Client (real-time data ingestion)
- REST Client (order management via HTTP)
- Order Book & Trade Data Handler
- Trading Strategy / Decision Engine
- Order Manager (place, cancel, track active orders)
- Balance Manager (get/update balances)
- Graceful Shutdown/Signal Handler
- Logging / Metrics

##### Relationships and Data Flows
a. Startup Sequence:
– Config Loader reads `Config` struct (env variables + defaults).
– Main initializes Tokio runtime, logger, and signal listener.
b. Data Ingestion Path:
– WebSocket Client ➔ connects to Coincheck’s WS API
– Incoming messages (order book snapshots, trades) ➔ dispatched to Order Book & Trade Data Handler
– Processed data ➔ sent to Trading Strategy Engine
c. Decision Path:
– Strategy Engine uses best bid/ask and config parameters ➔ decides “BUY” or “SELL” orders
– Sends order requests to Order Manager
d. Order Management Path:
– Order Manager invokes REST Client (via `reqwest`) to place/cancel orders
– REST responses ➔ updates Balance Manager & active-orders list
– Balance Manager may call REST Client to fetch latest balances
e. Graceful Shutdown Path:
– Signal Handler traps SIGINT/SIGTERM ➔ informs Order Manager to cancel all active orders ➔ waits for confirmations ➔ exits

##### Architectural Patterns & Design Principles
- Asynchronous, event-driven: uses Tokio for concurrency.
- Separation of concerns: distinct modules for config, data ingestion, strategy, order management.
- Layered design:
– Infrastructure Layer (WS & HTTP clients)
– Domain Layer (order book, strategy, manager)
– Application Layer (main startup & shutdown coordination)
- Dependency injection via module boundaries (each `src/exchanges/coincheck/*.rs` file encapsulates one API call).

##### Technologies & Libraries
– Tokio (async runtime, WebSocket streams)
– Reqwest (HTTP client)
– Serde / serde_json (JSON serialization)
– Env_logger (logging, controlled by RUST_LOG)
– Signal Hook (graceful shutdown)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        direction TB
        ConfigLoader["Config Loader<br/>(src/config.rs)"]:::config
        Runtime["Runtime & Orchestration<br/>(src/main.rs)"]:::internal
        Logger["Logging / Metrics"]:::config
        SignalHandler["Signal Handler<br/>(Graceful Shutdown)"]:::internal
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        WSClient["WebSocket Client<br/>(Order Book & Trade Data Ingestion)"]:::internal
        subgraph "REST Clients"
            direction TB
            PlaceOrder["Place Order"]:::internal
            CancelOrder["Cancel Order"]:::internal
            GetActiveOrders["Get Active Orders"]:::internal
            GetBalance["Get Balance"]:::internal
        end
        CoincheckWS["Coincheck WebSocket API"]:::external
        CoincheckREST["Coincheck REST API"]:::external
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        OrderBook["Order Book & Trade Data Handler"]:::internal
        Strategy["Trading Strategy / Decision Engine"]:::internal
        OrderManager["Order Manager"]:::internal
        BalanceManager["Balance Manager"]:::internal
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Util1["string_or_float.rs"]:::util
        Util2["opt_string_or_float.rs"]:::util
        Util3["vec_string_or_float.rs"]:::util
        Util4["util.rs"]:::util
        ExDefs["exchanges.rs<br/>coincheck.rs"]:::util
    end

    %% Flows
    ConfigLoader -->|reads config| Runtime
    Runtime -->|init logger| Logger
    Runtime -.->|trap SIGINT/SIGTERM| SignalHandler
    Runtime -->|spawn tasks| WSClient
    WSClient -->|JSON over WS| OrderBook
    CoincheckWS -->|WS feed| WSClient
    OrderBook -->|orderbook & trades| Strategy
    Strategy -->|decide BUY/SELL| OrderManager
    OrderManager -->|HTTP JSON POST| PlaceOrder
    OrderManager -->|HTTP JSON DELETE| CancelOrder
    OrderManager -->|HTTP JSON GET| GetActiveOrders
    GetActiveOrders -->|update| OrderManager
    PlaceOrder -->|response update| BalanceManager
    CancelOrder -->|response update| BalanceManager
    BalanceManager -->|HTTP JSON GET| GetBalance
    GetBalance -->|balances| BalanceManager
    BalanceManager -->|update balances| OrderManager
    OrderManager -->|orders| CoincheckREST
    PlaceOrder -->|to API| CoincheckREST
    CancelOrder -->|to API| CoincheckREST
    GetActiveOrders -->|to API| CoincheckREST
    GetBalance -->|to API| CoincheckREST

    %% Click Events
    click ConfigLoader "https://github.com/tnar/coincheck-rust/blob/main/src/config.rs"
    click Runtime "https://github.com/tnar/coincheck-rust/blob/main/src/main.rs"
    click WSClient "https://github.com/tnar/coincheck-rust/blob/main/src/exchanges/coincheck/get_order_books.rs"
    click PlaceOrder "https://github.com/tnar/coincheck-rust/blob/main/src/exchanges/coincheck/place_order.rs"
    click CancelOrder "https://github.com/tnar/coincheck-rust/blob/main/src/exchanges/coincheck/cancel_order.rs"
    click GetActiveOrders "https://github.com/tnar/coincheck-rust/blob/main/src/exchanges/coincheck/get_active_orders.rs"
    click GetBalance "https://github.com/tnar/coincheck-rust/blob/main/src/exchanges/coincheck/get_balance.rs"
    click OrderManager "https://github.com/tnar/coincheck-rust/tree/main/src/exchanges/coincheck"
    click Util1 "https://github.com/tnar/coincheck-rust/blob/main/src/string_or_float.rs"
    click Util2 "https://github.com/tnar/coincheck-rust/blob/main/src/opt_string_or_float.rs"
    click Util3 "https://github.com/tnar/coincheck-rust/blob/main/src/vec_string_or_float.rs"
    click Util4 "https://github.com/tnar/coincheck-rust/blob/main/src/util.rs"
    click ExDefs "https://github.com/tnar/coincheck-rust/blob/main/src/exchanges.rs"
    click ExDefs "https://github.com/tnar/coincheck-rust/blob/main/src/exchanges/coincheck.rs"

    %% Styles
    classDef external fill:#D6EAF8,stroke:#1B4F72
    classDef internal fill:#D5F5E3,stroke:#145A32
    classDef config fill:#F2F3F4,stroke:#566573
    classDef util fill:#F9E79F,stroke:#7D6608
```
