Crypto Live Updates

A real-time cryptocurrency price tracking application with a React.js frontend (built on Next.js) and a scalable Node.js WebSocket backend. Built with TypeScript and organized as a monorepo using pnpm workspaces.

---

🎯 Project Overview

Crypto Live Updates is a full-stack application designed to provide real-time cryptocurrency price updates. It features:

• Real-time WebSocket communication between backend and frontend for live price updates
• Browser automation using Playwright to scrape cryptocurrency prices from TradingView (or other sources)
• Event-driven architecture with EventEmitter for efficient price event handling
• Modern React.js UI built with Next.js 14 and styled with Tailwind CSS
• Type safety across the entire application using TypeScript
• Monorepo structure for better code organization and shared utilities

---

🏗️ Architecture

High-Level Flow

Playwright Browser (TradingView)
         ↓
    Price Events
         ↓
  EventEmitter Bus
         ↓
   Fastify Server
         ↓
  WebSocket Broadcast
         ↓
   Next.js Frontend
         ↓
   Live Price Display

Tech Stack

Backend

• Fastify - Fast and low-overhead Node.js web framework
• Playwright - Browser automation for scraping TradingView
• WebSocket Plugin - Real-time bidirectional communication
• Node.js EventEmitter - Event-driven in-memory price bus
• Connect RPC - Protocol for RPC communication

Frontend

• React.js 18 - Core UI library
• Next.js 14 - React.js framework with App Router
• Tailwind CSS - Utility-first CSS framework
• TypeScript - Type-safe JavaScript

Development Tools

• pnpm - Fast, disk space-efficient package manager with monorepo support
• tsx - TypeScript execution for Node.js
• TSC - TypeScript compiler

---

📁 Project Structure

crypto_live_updates/
├── apps/
│   └── web/                          # Next.js frontend application
│       ├── app/
│       │   ├── layout.tsx            # Root layout component
│       │   ├── page.tsx              # Home page with ticker management & live feed
│       │   └── ...
│       ├── styles/
│       │   └── globals.css           # Global Tailwind CSS
│       ├── package.json
│       ├── next.config.mjs           # Next.js configuration
│       ├── tailwind.config.mjs       # Tailwind CSS configuration
│       ├── postcss.config.mjs        # PostCSS configuration
│       └── tsconfig.json
│
├── packages/
│   ├── proto/                        # Shared protocol definitions
│   │   ├── src/
│   │   │   └── crypto.proto.ts       # Type definitions for price events
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   └── server/                       # Node.js backend server
│       ├── src/
│       │   └── index.ts              # Main server entry point
│       ├── dist/                     # Compiled JavaScript (generated)
│       ├── package.json
│       └── tsconfig.json
│
├── package.json                      # Root workspace configuration
├── pnpm-workspace.yaml               # pnpm workspace definition
├── tsconfig.base.json                # Shared TypeScript configuration
└── README.md                         # This file

---

🚀 Quick Start

Prerequisites

• Node.js v18 or higher
• pnpm v9.0.0 or higher (package manager)
• Modern web browser (Chrome, Firefox, Safari, or Edge)

Installation

1. Clone or navigate to the project directory:

cd crypto_live_updates

2. Install all dependencies across the monorepo:

pnpm install

This command installs dependencies for the root, apps/web, and all packages in the packages/ directory.

Running in Development

Option 1: Run Everything in Parallel

pnpm dev

This starts both the backend server and frontend development server simultaneously.

Option 2: Run Individually

Terminal 1 - Start the Backend Server:

cd packages/server
pnpm dev

The server will start on http://localhost:4000 with WebSocket endpoint at ws://localhost:4000/prices.

Terminal 2 - Start the Frontend Development Server:

cd apps/web
pnpm dev

Open your browser to http://localhost:3000 to view the application.

Accessing the Application

• Frontend: http://localhost:3000
• Backend: http://localhost:4000
• WebSocket Endpoint: ws://localhost:4000/prices

---

📡 Backend Server Details

Server Features

The backend server is built with Fastify and provides:

1. WebSocket Server: Broadcasts real-time cryptocurrency prices to connected clients
2. TradingView Scraper: Uses Playwright to monitor price changes on TradingView
3. Event Bus: Manages price update events efficiently using EventEmitter
4. RESTful API: Base HTTP endpoints for health checks and server management

Server Architecture

File: packages/server/src/index.ts

The server:

• Initializes a Playwright browser instance to navigate to TradingView
• Exposes a JavaScript function in the browser context to push price events
• Attaches a MutationObserver to monitor DOM changes (currently mocked with random prices)
• Emits price update events through the EventEmitter bus
• Broadcasts events to all connected WebSocket clients in real-time
• Listens on port 4000 (configurable via PORT environment variable)

Extending the Server

To connect real TradingView data:

1. Update the DOM selectors in the createTradingViewObserver function to match TradingView's actual HTML structure
2. Replace the random price generation with real DOM value extraction
3. Consider adding retry logic and error handling for robustness

---

🎨 Frontend Details

Frontend Features

The React.js frontend (built with Next.js App Router) provides:

1. Live Price Display: Shows real-time cryptocurrency prices as they update
2. Ticker Management: Add or remove cryptocurrency symbols to track
3. Event Log: Maintains a rolling log of the latest 200 price update events
4. Responsive Design: Mobile-friendly layout using Tailwind CSS
5. Reliable WebSocket Client: Automatic reconnect with backoff and re-subscription of active tickers
6. Optimistic UI + Ack Reconciliation: Shows pending add/remove states and finalizes actions on backend acknowledgement

Frontend Architecture

File: apps/web/app/page.tsx

The page component:

• Manages state for tracked tickers and price events
• Establishes and maintains a WebSocket connection to the backend
• Sends typed control messages (subscribe/unsubscribe) for ticker changes
• Reconciles optimistic UI updates using server ack responses
• Listens for incoming price update messages
• Maintains a sliding window of recent events (last 200)
• Provides UI controls to add/remove tickers
• Displays ticker list and event feed

User Interface

• Header: Shows application title
• Ticker Input Section: Add new cryptocurrency symbols to track
• Active Tickers List: Display all currently tracked symbols with removal buttons
• Live Event Feed: Shows real-time price updates with timestamps and sources
• Responsive Layout: Adapts to different screen sizes with Tailwind CSS

---

🔌 WebSocket Communication

Message Format

The websocket channel carries both control acknowledgements and price events.

Control message sent by frontend:

{
   "type": "control",
   "action": "subscribe",
   "symbol": "BTCUSDT",
   "requestId": "1713340000000-ab12cd"
}

Acknowledgement sent by backend:

{
   "type": "ack",
   "ok": true,
   "action": "subscribe",
   "symbol": "BTCUSDT",
   "requestId": "1713340000000-ab12cd"
}

Price event payload:

{
  "symbol": "BTCUSDT",
  "price": 42500.75,
  "timestampIso": "2024-02-17T10:30:45.123Z",
  "source": "tradingview-dom-mock"
}

Connection Lifecycle

1. Client connects: React.js frontend opens websocket to ws://localhost:4000/prices
2. Client subscribes: Frontend sends subscribe control messages for active tickers
3. Server tracks efficiently: Backend reference-counts symbols across all users, so duplicate symbol subscriptions share one upstream tracking resource
4. Events flow: Backend sends price events only to clients subscribed to that symbol
5. Ack reconciliation: Frontend resolves pending UI states from backend ack messages
6. Disconnection cleanup: On socket close, backend removes that user's symbol references and stops tracking symbols with zero subscribers

---

📦 Available Scripts

Root Level Scripts

# Start all services in parallel (backend + frontend)
pnpm dev

# Build all packages and applications
pnpm build

# Run linting across all workspaces (non-blocking)
pnpm lint

# Run tests across all workspaces (non-blocking)
pnpm test

# Install all dependencies
pnpm install:all

Backend Server Scripts

cd packages/server

# Development with hot reload (tsx watch)
pnpm dev

# Build TypeScript to JavaScript
pnpm build

# Start compiled server (after building)
pnpm start

Frontend Scripts

cd apps/web

# Development server with hot reload
pnpm dev

# Build for production
pnpm build

# Start production server (after building)
pnpm start

# Run ESLint
pnpm lint

---

🏭 Building for Production

Build the Entire Project

pnpm build

This command:

• Compiles TypeScript in all packages
• Builds the Next.js frontend for production
• Generates optimized output in dist/ directories

Run Production Server

1. Build backend:

cd packages/server
pnpm build

2. Start backend:

node dist/index.js

3. Build frontend:

cd apps/web
pnpm build

4. Start frontend:

pnpm start

---

🔧 Environment Variables

Backend Server

Create a .env file in packages/server/ (optional):

PORT=4000                  # Server port (default: 4000)
NODE_ENV=development       # Environment: development, production

Frontend

Create a .env.local file in apps/web/ (optional):

NEXT_PUBLIC_WS_HOST=localhost:4000

---

🛠️ Development Workflow

Adding a New Feature

1. Choose where to work:

   • Backend logic → packages/server/src/
   • Shared types → packages/proto/src/
   • Frontend UI → apps/web/app/

2. Run development server:

   pnpm dev

3. Make changes (files auto-reload)

4. Test manually at http://localhost:3000

Modifying Shared Types

Edit packages/proto/src/crypto.proto.ts to update shared type definitions used across the monorepo.

---

🧪 Testing

Currently, the project includes test script placeholders. To add tests:

1. Backend Unit Tests: Create .test.ts files in packages/server/src/
2. Frontend Tests: Use Jest or Vitest with React Testing Library
3. Run tests:

   pnpm test

---

🐛 Troubleshooting

Port Already in Use

If port 4000 or 3000 is already in use:

# Frontend - specify custom port
PORT=3001 pnpm dev  # in apps/web

# Backend - specify custom port
PORT=5000 pnpm dev  # in packages/server

WebSocket Connection Failed

• Verify backend server is running on http://localhost:4000
• Check browser console for error messages
• Ensure firewall doesn't block WebSocket connections
• Try clearing browser cache and reloading

Dependencies Installation Issues

# Clear pnpm cache
pnpm store prune

# Reinstall all dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install

TypeScript Errors

# Rebuild TypeScript
pnpm build

# Check for type errors
cd packages/server && npx tsc --noEmit

---

📚 Additional Resources

• Next.js Documentation
• Fastify Documentation
• Playwright Documentation
• Tailwind CSS Documentation
• TypeScript Handbook
• pnpm Workspaces

---

📝 License

This project is open source and available under the MIT License.

---

👤 Author

Prerna

• Active development and maintenance of the Crypto Live Updates project