Architecture

Overview

Based Terminal MiniApps use a secure, sandboxed architecture built on browser standards. This guide explains how the system works, from high-level communication patterns to low-level implementation details.

High-Level Architecture

Key Components

1. Based Terminal - The host application that manages MiniApps

2. MiniApp SDK - The client library you use to communicate with the terminal

3. Sandbox iframe - Isolated environment where your code runs

4. PostMessage API - Browser-native communication channel

Communication Architecture

Message Flow

Command System

The SDK provides strongly-typed commands for all terminal operations:

Event System

Real-time updates flow from the terminal to your MiniApp:

Security Architecture

Sandbox Isolation

Permission Model

Permission Types

Permissions are grouped by category:

Category	Permissions
Market Data	read_market_data, read_orderbook, read_candles
Trading	place_orders, cancel_orders, modify_orders, populate_orders
Account	read_account, read_positions, read_orders, read_balance, read_trades
UI	read_navigation, write_navigation, write_chart, send_notifications
Settings	read_user_settings, modify_user_settings
Advanced	execute_strategies, access_analytics

Data Flow Architecture

Market Data Pipeline

Order Execution Flow

SDK Architecture

Core SDK Layers

React Integration Architecture

State Management

Connection State

Permission State

Performance Optimization

Message Batching

Caching Strategy

Error Handling

Error Flow

Best Practices

Connection Management

// Always handle connection events
client.on('connected', ({ sessionId }) => {
  console.log('Connected:', sessionId);
});

client.on('disconnected', () => {
  console.log('Disconnected - will auto-reconnect');
});

client.on('error', (error) => {
  console.error('Error:', error);
});

Permission Handling

// Check permissions before operations
if (client.hasPermission('place_orders')) {
  await client.placeOrder(orderData);
} else {
  // Request permission
  const granted = await client.requestPermissions(['place_orders']);
  if (granted.includes('place_orders')) {
    await client.placeOrder(orderData);
  }
}

Event Management

// Clean up event listeners
useEffect(() => {
  const handler = (data) => {
    console.log('Market data:', data);
  };

  client.on('market.bbo', handler);

  return () => {
    client.off('market.bbo', handler);
  };
}, [client]);

Error Recovery

// Implement retry logic for transient errors
async function placeOrderWithRetry(orderData, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.placeOrder(orderData);
    } catch (error) {
      if (error.code === 'NETWORK_ERROR' && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
        continue;
      }
      throw error;
    }
  }
}

Technical Considerations

Why iframe Sandboxing?

• Security: Complete isolation from terminal code

• Stability: MiniApp crashes don't affect terminal

• Flexibility: Support any web technology

• Updates: Independent deployment and versioning

Why PostMessage?

• Security: Controlled communication channel

• Standards: Built on web standards

• Reliability: Browser-native implementation

• Debugging: Easy to inspect and debug

Why Event-Driven Design?

• Real-time: Immediate updates from markets

• Scalability: Efficient one-to-many broadcasting

• Flexibility: Easy to add new event types

• Performance: Non-blocking operations

Next Steps

• API Reference - Complete SDK documentation

• React Examples - React integration patterns

• Vanilla JS Examples - Pure JavaScript examples