Scanstream - Advanced Cryptocurrency Trading Platform

A sophisticated full-stack cryptocurrency trading platform featuring real-time market analysis, AI-powered signal generation, automated trading strategies, and comprehensive backtesting capabilities.

🚀 Overview

Scanstream is a modern, production-ready trading platform designed for cryptocurrency markets. It combines advanced technical analysis, machine learning-driven signals, and automated execution with a focus on risk management and performance optimization.

Key Capabilities

• Real-time Market Data: Live price feeds, order book analysis, and market microstructure monitoring
• AI-Powered Signals: 13 specialized trading agents providing consensus-based signal generation
• Automated Trading: Strategy execution with configurable risk management and position sizing
• Comprehensive Backtesting: Historical performance analysis across multiple timeframes and assets
• Advanced Analytics: Performance metrics, drawdown analysis, and optimization tools
• Multi-Asset Support: Cryptocurrency, forex, and traditional assets with unified data handling

� Vision

Scanstream is more than a signal engine — it is the perceptual layer for a self-improving trading intelligence. The platform is designed to learn from every trade, adapt its strategy weights, and evolve toward minimal human intervention as part of a broader autonomous agent architecture.

This vision includes:

• Persistent learning from trade outcomes, market conditions, and agent consensus
• Adaptive intelligence with dynamic weight tuning across signal sources and agents
• Clustering insights to understand market behaviour, regime transitions, and structural patterns
• Asset velocity modeling to capture momentum, flow, and liquidity strength across markets
• Asset graph analysis to map relationships, cross-asset influence, and propagation of market moves
• Autonomous perception as the foundation for future self-managing trading agents

The goal is for Scanstream to become the observability layer that feeds larger autonomous systems with market awareness, signal quality, and confidence metrics — not just a single execution pipeline.

�🏗️ Architecture

System Architecture Overview

graph TB
    subgraph "Frontend Layer"
        UI[React Dashboard]
        Charts[Trading Charts]
        Signals[Signal Display]
    end

    subgraph "API Layer"
        REST[REST API]
        WS[WebSocket Server]
        Auth[Authentication]
    end

    subgraph "Core Services"
        Agents[13 Trading Agents]
        Engine[Trading Engine]
        Backtest[Backtesting Engine]
        Risk[Risk Management]
    end

    subgraph "Data Layer"
        Cache[In-Memory Cache]
        DB[(PostgreSQL)]
        Feeds[Market Data Feeds]
    end

    UI --> REST
    Charts --> WS
    Signals --> WS
    REST --> Agents
    WS --> Engine
    Agents --> Engine
    Engine --> Risk
    Engine --> Backtest
    Risk --> DB
    Backtest --> DB
    Cache --> DB
    Feeds --> Cache

Loading

Component Architecture

graph LR
    subgraph "Trading Agents"
        VFMD[VFMD Physics Agent]
        Flow[Flow Field Agent]
        UT_BOT[UT Bot Agent]
        Structure[Structure Agent]
        ML[ML Prediction Agent]
        Pattern[Pattern Detection Agent]
        Volume[Volume Metrics Agent]
    end

    subgraph "Signal Processing"
        Aggregator[Signal Aggregator]
        Router[Regime Router]
        Sizer[Position Sizer]
    end

    subgraph "Execution"
        Orders[Order Manager]
        Positions[Position Tracker]
        P&L[P&L Calculator]
    end

    VFMD --> Aggregator
    Flow --> Aggregator
    UT_BOT --> Aggregator
    Structure --> Aggregator
    ML --> Aggregator
    Pattern --> Aggregator
    Volume --> Aggregator

    Aggregator --> Router
    Router --> Sizer
    Sizer --> Orders
    Orders --> Positions
    Positions --> P&L

Loading

Data Flow Architecture

sequenceDiagram
    participant Market
    participant Feed
    participant Cache
    participant Agents
    participant Engine
    participant UI

    Market->>Feed: Price Updates
    Feed->>Cache: Store Data
    Cache->>Agents: Market Data
    Agents->>Engine: Signals
    Engine->>UI: Trading Signals
    UI->>Engine: Trade Orders
    Engine->>Market: Execute Orders

Loading

✨ Features

Core Trading Features

• Multi-Agent Signal Generation: 13 specialized agents providing diverse trading perspectives
• Regime-Aware Trading: Automatic adaptation to trending, sideways, and volatile market conditions
• Dynamic Position Sizing: Kelly Criterion-based sizing with risk-adjusted multipliers
• Advanced Risk Management: Stop-loss, take-profit, and drawdown controls
• Real-time Execution: WebSocket-based order execution with slippage monitoring

Analysis & Backtesting

• Comprehensive Backtesting: Historical performance analysis with walk-forward validation
• Performance Analytics: Sharpe ratio, Sortino ratio, Calmar ratio, and custom metrics
• Strategy Optimization: Parameter sweeps and genetic algorithm optimization
• Paper Trading: Risk-free strategy testing with realistic market simulation

Data & Integration

• Multi-Source Data Feeds: CCXT, Polygon.io, CoinGecko, and Yahoo Finance integration
• Real-time WebSocket Streams: Live price updates and order book data
• Database Persistence: PostgreSQL with Drizzle ORM for reliable data storage
• API-First Design: RESTful APIs for all platform functionality

User Interface

• Modern React Dashboard: Intuitive trading interface with real-time updates
• Advanced Charting: Technical analysis charts with custom indicators
• Signal Visualization: Agent consensus display with confidence scoring
• Portfolio Management: Position tracking and performance monitoring

🛠️ Technology Stack

Frontend

• React 18 - Modern React with hooks and concurrent features
• TypeScript - Type-safe development across the entire application
• Vite - Fast build tool and development server
• TailwindCSS - Utility-first CSS framework
• shadcn/ui - High-quality component library
• TanStack Query - Powerful data fetching and caching
• Recharts - Composable charting library
• Wouter - Lightweight routing library

Backend

• Node.js - Server-side JavaScript runtime
• Express.js - Fast, unopinionated web framework
• TypeScript - Type safety for backend code
• WebSocket - Real-time bidirectional communication
• Drizzle ORM - Type-safe database toolkit
• PostgreSQL - Robust relational database
• Neon Database - Serverless PostgreSQL provider

Trading Engine

• Custom Signal Pipeline - Multi-agent signal aggregation
• Technical Analysis Library - Comprehensive indicator calculations
• Risk Management Engine - Advanced position and portfolio risk controls
• Backtesting Framework - Historical simulation and optimization

Development Tools

• ESLint - Code linting and formatting
• Prettier - Code formatting
• Husky - Git hooks for quality assurance
• Jest - Testing framework
• Docker - Containerization for deployment

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• PostgreSQL database (or Neon account)
• Git

Installation

1. Clone the repository

   git clone https://github.com/yourusername/scanstream.git
   cd scanstream

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your database URL and API keys

4. Set up the database

   npm run db:generate
   npm run db:migrate
   npm run db:seed

5. Start the development server

   npm run dev

6. Open your browser

   http://localhost:5173
   

Docker Deployment

# Build and run with Docker
docker build -t scanstream .
docker run -p 3000:3000 -p 5000:5000 scanstream

📊 Usage

Basic Trading Workflow

1. Market Analysis

   • View real-time price charts with technical indicators
   • Monitor agent consensus signals
   • Analyze market regime and volatility

2. Strategy Configuration

   • Select trading strategies from the strategy library
   • Configure risk parameters and position sizing
   • Set up entry and exit conditions

3. Backtesting

   • Run historical simulations on selected strategies
   • Analyze performance metrics and drawdown
   • Optimize parameters for better results

4. Live Trading

   • Enable automated execution with risk controls
   • Monitor positions and P&L in real-time
   • Receive alerts for significant market events

API Usage

// Generate trading signals
const signals = await fetch('/api/signals/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    symbol: 'BTC/USDT',
    timeframe: '1h',
    accountBalance: 10000
  })
});

// Execute a trade
const trade = await fetch('/api/trades/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    symbol: 'BTC/USDT',
    side: 'BUY',
    quantity: 0.01,
    price: 45000
  })
});

📚 API Documentation

REST Endpoints

Market Data

• GET /api/market/prices - Get current market prices
• GET /api/market/orderbook/:symbol - Get order book data
• GET /api/market/history/:symbol - Get historical price data

Trading Signals

• POST /api/signals/generate - Generate trading signals
• GET /api/signals/history - Get signal history
• GET /api/signals/consensus - Get agent consensus

Trading Operations

• POST /api/trades/execute - Execute a trade
• GET /api/trades/positions - Get current positions
• GET /api/trades/history - Get trade history

Backtesting

• POST /api/backtest/run - Run a backtest
• GET /api/backtest/results/:id - Get backtest results
• GET /api/backtest/strategies - List available strategies

WebSocket Events

// Connect to WebSocket
const ws = new WebSocket('ws://localhost:5000');

// Subscribe to market data
ws.send(JSON.stringify({
  type: 'subscribe',
  channels: ['prices', 'signals']
}));

// Handle incoming messages
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'price_update') {
    // Handle price update
  } else if (data.type === 'signal_update') {
    // Handle signal update
  }
};

🔧 Configuration

Environment Variables

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/scanstream

# API Keys
POLYGON_API_KEY=your_polygon_key
COINGECKO_API_KEY=your_coingecko_key

# Trading
MAX_POSITION_SIZE=0.05
MAX_DRAWDOWN=0.15
DEFAULT_LEVERAGE=1

# Server
PORT=5000
NODE_ENV=development

Trading Configuration

{
  "strategies": {
    "momentum": {
      "enabled": true,
      "parameters": {
        "lookback": 20,
        "threshold": 0.02
      }
    },
    "mean_reversion": {
      "enabled": false,
      "parameters": {
        "deviation": 2.0,
        "hold_time": 24
      }
    }
  },
  "risk_management": {
    "max_drawdown": 0.15,
    "max_position_size": 0.05,
    "stop_loss_multiplier": 1.5
  }
}

🧪 Testing

Running Tests

# Run all tests
npm test

# Run specific test suite
npm test -- --testPathPattern=trading-engine

# Run with coverage
npm run test:coverage

Backtesting

# Run backtest for a strategy
npm run backtest -- --strategy=momentum --symbol=BTC/USDT --start=2023-01-01 --end=2024-01-01

# Run optimization
npm run optimize -- --strategy=momentum --parameters=lookback,threshold

📈 Performance

Benchmark Results

Metric	Value	Target
Signal Generation Latency	<50ms	<100ms
WebSocket Message Throughput	1000+ msg/s	500+ msg/s
Backtest Execution Time	<30s for 1 year	<60s for 1 year
Memory Usage	<200MB	<500MB
API Response Time	<200ms	<500ms

Scalability

• Concurrent Users: Supports 100+ simultaneous connections
• Data Processing: Handles 1000+ symbols with real-time updates
• Backtesting: Processes 10+ years of historical data efficiently
• Database: Optimized queries with proper indexing

🤝 Contributing

Development Workflow

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Make your changes
4. Run tests and linting

   npm run test
   npm run lint

5. Commit your changes

   git commit -m "feat: add your feature description"

6. Push to your branch

   git push origin feature/your-feature-name

7. Create a Pull Request

Code Standards

• TypeScript: Strict type checking enabled
• ESLint: Airbnb configuration with React rules
• Prettier: Consistent code formatting
• Testing: Minimum 80% code coverage
• Documentation: JSDoc comments for public APIs

Commit Convention

type(scope): description

Types:
- feat: new feature
- fix: bug fix
- docs: documentation
- style: formatting
- refactor: code restructuring
- test: testing
- chore: maintenance

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• CCXT - Cryptocurrency exchange library
• Technical Analysis Libraries - Indicator calculations
• Open Source Community - Various dependencies and inspiration

📞 Support

• Documentation: docs/ directory
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Built with ❤️ for the cryptocurrency trading community