# System Architecture

**CryptoStruct** is built to run thousands of strategies across multiple
exchanges. Two constraints shape the architecture: strategies typically need
to live close to the exchanges they trade against (latency dominates
everything else), and a single firm typically operates in more than one
region.

The deployment model is regional. A **region** is a physical or cloud
location: an AWS region, Azure, Google Cloud, Alibaba Cloud, or a private
co-location site. Each region can host any number of trading components.

---

## Example architecture

![Example Trading System|600](/static/images/system-architecture.png)

---

### Primary region

The **primary region** hosts the core backend services: system control,
monitoring, data storage, and the user-facing interfaces and APIs. It can
also host trading components (Strategy Server, Trading Adapter), which is
useful when most trading activity is concentrated there.

In the diagram above, Tokyo is the primary region. It manages the overall
system and runs local trading infrastructure.

### Other regions

Any number of additional regions can run alongside the primary region. Each
runs its own Strategy Servers and Trading Adapters, placing strategies close
to the exchanges they trade against to cut order round-trip times.

### Deployment topology

The typical layout puts one Strategy Server and one Trading Adapter on each
hardware server. A Strategy Server can connect to multiple Trading Adapters
when it needs to reach exchanges in different regions.

Two examples:

- A Strategy Server in London trades on Deribit (London) and Kraken (North
  Virginia) by connecting to separate Trading Adapters in each region.
- A Strategy Server in Tokyo trades on Binance and Gate.io through a single
  local Trading Adapter.

Both layouts are valid. Pick based on latency, account, and strategy
requirements.

CryptoStruct also operates dedicated lines between regions that provide
better network latency than regular internet connections.

---

## Backend components

### Backend

The **Backend** is an Apache-served web application that is the central
interface for managing and monitoring the trading system.

What it does:

- Manages strategy instances across all regions
- Adds and removes Strategy Servers and Trading Adapters
- Manages trading accounts and connections
- Shows wallets, positions, open orders, and trades
- Shows real-time PnL and market data
- Provides manual order entry (click trading)
- Browses supported exchanges and instruments

The backend also exposes HTTP APIs for external tools, providing:

- Master data and statistics for exchanges and instruments
- Trading data published by components such as the Trading Adapter

![Backend Web UI|600](/static/images/screen-backend.png)

---

### Trading Hub

The **Trading Hub** connects to all Trading Adapters and the Market Data
Service. It supports manual click trading, monitors public market data,
and displays the trading activity of running strategies in real time.

---

### Graylog *(optional)*

**Graylog** collects and indexes log messages from every system component,
with centralised search and filtering.

![Graylog|600](/static/images/screen-graylog.png)

---

### Prometheus and Grafana *(optional)*

- **Prometheus** collects and stores metrics on performance, health, and
  trading activity from the other components.
- **Grafana** visualises those metrics. Ready-to-use dashboards for
  latencies and trading activity ship out of the box.

![Grafana|600](/static/images/screen-grafana.png)

---

## Core trading components

The **Market Data Adapter** (MDA), **Strategy Server** (STR), and **Trading
Adapter** (TA) are the three components that move market data, run
strategies, and flow orders. All three are built for high throughput and low
latency.

![Trading Architecture|600](/static/images/trading-architecture.png)

---

### Market Data Adapter (MDA)

The MDA is part of the managed CryptoStruct Market Data Service. It provides
low-latency real-time data streams.

- Normalises native exchange data into the CryptoStruct Market Data Protocol
- Maintains multiple connections to an exchange for redundancy and latency
  optimisation

---

### Strategy Server (STR)

The STR runs the strategies you write with the SDK.

- Connects to multiple MDAs and TAs for data and order routing
- Distributes strategy instances across CPU cores to balance load
- Routes market data and trading events to the right strategy instance
- Enforces per-account and per-instrument risk limits
- Calculates **Theoretical Profit and Loss** (TPL) for every strategy

---

### Trading Adapter (TA)

Each trading account is bound to a TA, which talks to the exchange and
handles all trading events for that account.

- Maintains multiple connections to exchanges for all accounts
- Normalises native exchange order-entry protocols into the CryptoStruct
  format
- Speaks **WebSocket**, **REST**, and **FIX** (whichever the exchange offers)
- Tracks and enforces rate limits to prevent the user from being blocked
  due to violations
- Reports orders and trades back to the backend

---