Stock Trading Assistant

Real-time stock trading signals with AI chat assistance, built with dependency injection architecture for seamless switching between mock and real data sources.

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Clone the repository
git clone <repository-url>
cd stock-trading-assistant

# Install all workspace dependencies
npm install

# Build all packages (common-utils → backend → frontend)
npm run build

Start the Server

Development Mode (Mock Data)

npm run start:backend

• Uses mock data for development
• Signals every 4 seconds
• No API keys required

Demo Mode (Fast Mock Data)

npm run start:backend:demo

• Fast mock data every 2 seconds
• Perfect for demonstrations
• Realistic trading signals with events

Production Mode (Real Data)

# Set your API key
export BENZINGA_API_KEY=your_api_key_here
npm run start:backend:real

• Uses real Benzinga API data
• Requires valid API key
• Live market data and events

Start the Frontend

npm run start:frontend

• Opens at http://localhost:3000
• Connects to WebSocket server at ws://localhost:8080
• Real-time signal display and chat interface

🏗️ Architecture

Monorepo Structure

The application uses a clean monorepo architecture with three main packages:

stock-trading-assistant/
├── common-utils/          # Shared types, interfaces, models
├── backend/              # WebSocket server, data sources, business logic
└── frontend/             # React UI, WebSocket client, user interface

Dependency Injection System

The backend uses a complete dependency injection architecture:

Environment Config → DI Container → Factory → Data Source
                                         ↓
WebSocket Clients ← WebSocket Server ← Signal Service

Key Components

• Common Utils: Shared Signal types, interfaces (ISignalDataSource, IWebSocketServer)
• Backend: WebSocket server, data sources (Mock/Benzinga), dependency injection
• Frontend: React components, WebSocket client, real-time UI
• Factory Pattern: Creates appropriate implementations based on configuration

📡 WebSocket API

Client → Server Messages

Subscribe to Stock

{
  "type": "subscribe",
  "symbol": "AAPL"
}

Unsubscribe from Stock

{
  "type": "unsubscribe",
  "symbol": "AAPL"
}

Server → Client Messages

Trading Signal

{
  "type": "signal",
  "data": {
    "symbol": "AAPL",
    "recommendation": "BUY",
    "confidence": 0.87,
    "reasoning": "Earnings beat expectations by 4.7%",
    "timestamp": "2024-01-15T16:30:00.000Z",
    "price": 185.50,
    "change": 2.30,
    "changePercent": 1.26,
    "upcomingEvent": {
      "type": "EARNINGS",
      "date": "2024-01-20T21:30:00.000Z",
      "description": "Q4 2024 Earnings Call",
      "importance": "HIGH"
    }
  }
}

⚙️ Configuration

Environment Variables

Variable	Description	Default	Example
SIGNAL_DATA_MODE	Data source mode	mock	mock, real, hybrid
WS_PORT	WebSocket server port	8080	8080
MOCK_DATA_INTERVAL	Mock signal interval (ms)	4000	2000
ENABLE_EVENTS	Include upcoming events	true	true, false
BENZINGA_API_KEY	Benzinga API key	-	your_api_key
FOCUS_STOCKS	Priority stocks	AAPL,TSLA,NVDA	AAPL,MSFT,GOOGL

Advanced Configuration

# Custom startup with specific settings
./scripts/start-server.sh --mode mock --port 8080 --interval 2000

# Real data mode with custom port
BENZINGA_API_KEY=your_key ./scripts/start-server.sh --mode real --port 9000

# Fast testing mode without events
./scripts/start-server.sh --mode mock --interval 1000 --no-events

🧪 Testing

Run the Complete Demo

node demo-di-system.js

This will:

• Start the server with fast mock data
• Connect a WebSocket client
• Subscribe to AAPL, TSLA, NVDA
• Display 5 realistic trading signals
• Demonstrate the complete system flow

Manual WebSocket Testing

// Browser console or Node.js
const ws = new WebSocket('ws://localhost:8080');

ws.onopen = () => {
  console.log('Connected!');
  ws.send(JSON.stringify({
    type: 'subscribe',
    symbol: 'AAPL'
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
};

Unit Tests

npm test

📊 Available NPM Scripts

Script	Description
npm run start:dev	Development mode with mock data
npm run start:demo	Demo mode with fast mock data
npm run start:real	Production mode with real data
npm run start:fast	Testing mode with very fast mock data
npm run build	Build TypeScript to JavaScript
npm run test	Run unit tests
npm run lint	Run ESLint

🔧 Development

Project Structure

src/
├── backend/                 # Server-side code
│   ├── di/                 # Dependency injection
│   ├── factories/          # Factory implementations
│   ├── services/           # Business logic services
│   ├── websocket/          # WebSocket server
│   └── server.ts           # Main entry point
├── frontend/               # React frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── hooks/          # Custom hooks
│   │   └── pages/          # Page components
│   └── public/
└── services/               # Shared services
    └── data-sources/       # Data source implementations

Adding New Data Sources

1. Implement the Interface

export class YahooFinanceDataSource implements ISignalDataSource {
  // Implement all interface methods
}

2. Update the Factory

// In DataSourceFactory.ts
case 'yahoo':
  return new YahooFinanceDataSource(config);

3. Configure Environment

SIGNAL_DATA_MODE=yahoo YAHOO_API_KEY=your_key npm run start:real

🎯 Features

Phase 1 (Completed)

• ✅ Real-time WebSocket signal streaming
• ✅ Mock data source with realistic signals
• ✅ Dependency injection architecture
• ✅ React frontend with live signal display
• ✅ Focus stock selection (AAPL, TSLA, NVDA, etc.)
• ✅ Connection status monitoring
• ✅ Signal history and performance tracking

Phase 2 (Planned)

• 🚧 Enhanced signal reasoning (6-second comprehensive analysis)
• 🚧 Sentiment analysis integration
• 🚧 Technical indicators (RSI, moving averages)
• 🚧 Data reconciliation across sources

Phase 3 (Planned)

• 🚧 Interactive AI chat system
• 🚧 AWS AppSync integration
• 🚧 Persistent chat history
• 🚧 Context-aware responses

📚 Documentation

• DI_ARCHITECTURE.md - Detailed dependency injection architecture
• IMPLEMENTATION_SUMMARY.md - Implementation summary and benefits
• DEMO_GUIDE.md - Demo and testing guide
• .kiro/specs/stock-trading-assistant/ - Complete specification

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🆘 Support

For issues and questions:

1. Check the documentation files
2. Run the demo script to verify setup
3. Check WebSocket connection at ws://localhost:8080
4. Verify environment variables are set correctly

---

Built with dependency injection for clean, testable, and maintainable code 🚀