Skip to content
TradeX Documentation

Communication Patterns

This document describes the communication patterns used between services in the TradeX platform.

Communication Methods

Section titled “Communication Methods”

REST APIs

Section titled “REST APIs”

REST APIs are used for:

  • External-facing APIs: Client-facing endpoints
  • Admin APIs: Administrative operations
  • Service-to-service: When real-time performance is not critical

Characteristics:

  • HTTP/HTTPS protocol
  • JSON payloads
  • Stateless requests
  • Standard HTTP methods (GET, POST, PUT, DELETE)

Example:

// Order Service REST API
POST /v1/orders
Content-Type: application/json
{
  "instrumentId": "...",
  "side": "buy",
  "type": "limit",
  "quantity": 10.5,
  "price": 50000.0
}

gRPC

Section titled “gRPC”

gRPC is used for:

  • Internal service communication: High-performance internal APIs
  • Real-time data access: When low latency is required
  • Streaming data: Server-side streaming for real-time updates

Characteristics:

  • HTTP/2 protocol
  • Protocol Buffers (protobuf) serialization
  • Type-safe service definitions
  • Bidirectional streaming support

Example:

// Wallet Service gRPC
service WalletService {
  rpc GetBalance(GetBalanceRequest) returns (Balance);
  rpc HoldBalance(HoldBalanceRequest) returns (HoldResponse);
}

Kafka Events

Section titled “Kafka Events”

Kafka is used for:

  • Event-driven architecture: Asynchronous event processing
  • Event sourcing: Maintaining event history
  • Service decoupling: Loose coupling between services

Characteristics:

  • Asynchronous messaging
  • Event ordering per partition
  • At-least-once delivery guarantees
  • Schema registry for type safety

Example Topics:

  • engine.event.v1 - Matching engine events
  • md.instrument.created.v1 - Instrument creation events
  • wallet.balance.changed.v1 - Balance change events

WebSocket

Section titled “WebSocket”

WebSocket is used for:

  • Real-time data streaming: Live market data updates
  • Client push notifications: Real-time notifications to clients

Characteristics:

  • Full-duplex communication
  • Low latency
  • Persistent connections
  • Sub-protocol support

Example:

// WebSocket subscription
{
  "op": "subscribe",
  "channels": [
    {
      "name": "book",
      "symbols": ["BTCUSDT-PERP"]
    }
  ]
}

Communication Patterns

Section titled “Communication Patterns”

Request-Response Pattern

Section titled “Request-Response Pattern”

Used for synchronous operations where immediate response is required.

Examples:

  • REST API calls
  • gRPC service calls
  • Database queries

Flow:

Client → Service → Response

Event-Driven Pattern

Section titled “Event-Driven Pattern”

Used for asynchronous operations and service decoupling.

Examples:

  • Order events
  • Trade events
  • Configuration changes

Flow:

Service A → Kafka → Service B (async)

Pub-Sub Pattern

Section titled “Pub-Sub Pattern”

Used for broadcasting events to multiple consumers.

Examples:

  • Market data updates
  • Configuration changes
  • System notifications

Flow:

Publisher → Kafka Topic → Multiple Subscribers

Request-Stream Pattern

Section titled “Request-Stream Pattern”

Used for streaming data from server to client.

Examples:

  • Real-time market data
  • Configuration watch streams
  • Order book updates

Flow:

Client → Service → Stream (continuous)

Service Communication Matrix

Section titled “Service Communication Matrix”
ServiceMethodTargetPurpose
Order → WalletgRPCWallet ServiceBalance checks, holds
Order → MetadatagRPCMetadata ServiceInstrument validation
Order → Matching EngineKafkaMatching EngineOrder submission
Matching Engine → Market DataKafkaMarket Data ServiceTrade events
Market Data → ClientsWebSocketClientsReal-time updates
Metadata → ServicesKafkaAll ServicesConfiguration changes
Auth → UserKafkaUser ServiceUser events
Wallet → ServicesKafkaAll ServicesBalance changes

Best Practices

Section titled “Best Practices”

When to Use REST

Section titled “When to Use REST”
  • External-facing APIs
  • CRUD operations
  • When HTTP caching is beneficial
  • When tooling/ecosystem support is important

When to Use gRPC

Section titled “When to Use gRPC”
  • Internal service communication
  • When low latency is critical
  • When type safety is important
  • When streaming is needed

When to Use Kafka

Section titled “When to Use Kafka”
  • Event-driven workflows
  • Service decoupling
  • Event sourcing
  • When eventual consistency is acceptable

When to Use WebSocket

Section titled “When to Use WebSocket”
  • Real-time data streaming
  • Push notifications
  • When low latency is critical
  • When persistent connections are beneficial

Error Handling

Section titled “Error Handling”

REST APIs

Section titled “REST APIs”
  • Standard HTTP status codes
  • Error response bodies with details
  • Retry logic in clients

gRPC

Section titled “gRPC”
  • gRPC status codes
  • Error details in response
  • Retry with exponential backoff

Kafka

Section titled “Kafka”
  • Dead letter queues for failed messages
  • Retry mechanisms in consumers
  • Idempotent message processing

WebSocket

Section titled “WebSocket”
  • Error messages in WebSocket frames
  • Connection retry logic
  • Graceful degradation

Security

Section titled “Security”

Authentication

Section titled “Authentication”
  • JWT tokens for REST APIs
  • mTLS for gRPC (optional)
  • API keys for service-to-service
  • WebSocket authentication via gateway

Authorization

Section titled “Authorization”
  • Role-based access control (RBAC)
  • Service-level permissions
  • Resource-level permissions

Encryption

Section titled “Encryption”
  • TLS for all external communication
  • mTLS for internal gRPC (optional)
  • Encrypted Kafka messages (optional)

Monitoring

Section titled “Monitoring”

Metrics

Section titled “Metrics”
  • Request latency
  • Error rates
  • Throughput
  • Connection counts

Tracing

Section titled “Tracing”
  • Distributed tracing across services
  • Request correlation IDs
  • Span tracking

Logging

Section titled “Logging”
  • Structured logging
  • Request/response logging
  • Error logging
  • Event logging
Section titled “Related Documentation”