Skip to content

ADR 008: Control Interface Architecture

Status

Accepted

Context

Users need to control the trading system, monitor positions, and manage strategies. The interface must support: - Mobile access for traders on-the-go - Push notifications for important events (fills, alerts, circuit breakers) - Programmatic access for automation and third-party integrations - Low latency for time-sensitive operations

Decision

Implement a dual-interface architecture: 1. Telegram Bot as the primary mobile interface (Python) 2. REST/gRPC API for programmatic access (Rust/Axum)

Architecture

┌─────────────────────────────────────────┐
│           Telegram Bot (Python)          │
│  ┌─────────────────────────────────────┐│
│  │      python-telegram-bot            ││
│  │  • Command Handlers                 ││
│  │  • Callback Query Handlers          ││
│  │  • Inline Keyboards                 ││
│  └─────────────────┬───────────────────┘│
│                    │ gRPC                │
└────────────────────┼────────────────────┘
                     │
┌────────────────────▼────────────────────┐
│         Core Engine (Rust)               │
│  ┌─────────────────────────────────────┐│
│  │     tonic gRPC Server               ││
│  │  • UserService                      ││
│  │  • TradingService                   ││
│  │  • StrategyService                  ││
│  └─────────────────────────────────────┘│
└──────────────────────────────────────────┘

Interface Responsibilities

Interface Use Case Advantages
Telegram Mobile trading, alerts, quick actions Always accessible, push notifications
REST API Programmatic access, dashboards Stateless, well-understood
gRPC Bot-to-core communication Type-safe, efficient

Alternatives Considered

Approach Pros Cons Verdict
Telegram + REST Mobile-native, broad access Two codebases Chosen
Discord Bot Similar to Telegram Less trading-focused community Rejected
Web-only Single codebase No push notifications on mobile Rejected
CLI-only Simple Not accessible on mobile Rejected

Consequences

Positive

  • Mobile-first experience via Telegram
  • Push notifications for time-sensitive events
  • Programmatic access for power users
  • Clean separation of concerns (UI vs core)

Negative

  • Two languages (Python for bot, Rust for core)
  • gRPC interface maintenance overhead
  • Telegram dependency for primary interface

Neutral

  • Web dashboard can be added later using REST API

References

Linked Requirements

  • NFR-ARCH-005: Support Telegram and REST/gRPC control interfaces
  • FR-API-001: Full programmatic access to all features
  • FR-API-002: JWT authentication with refresh tokens