Skip to content

README.md

Latest commit

 

History

History
290 lines (219 loc) · 8.04 KB

README.md

File metadata and controls

290 lines (219 loc) · 8.04 KB

Stock/Crypto Alert System

A real-time price alert system for stocks and cryptocurrencies. Get notified when your favorite assets hit target prices through email and WebSocket notifications.

🚀 Features

  • User Authentication: Secure JWT-based authentication with refresh tokens
  • Price Alerts: Create, manage, and monitor price alerts for stocks and cryptocurrencies
  • Real-time Updates: WebSocket connections for live price updates and alert triggers
  • Multi-Asset Support: Support for both stocks (via Yahoo Finance) and cryptocurrencies (via Binance API)
  • Email Notifications: Email alerts when price targets are reached
  • Market Data API: Fetch current prices, validate symbols, and get bulk price data
  • Redis Caching: Optimized performance with Redis caching for market data
  • Background Monitoring: Automated scheduler for checking and triggering alerts
  • Modern UI: Beautiful, responsive React frontend with Tailwind CSS

🛠️ Tech Stack

Backend

  • FastAPI - Modern Python web framework
  • PostgreSQL - Relational database with asyncpg
  • Redis - Caching and session management
  • SQLAlchemy - ORM with async support
  • Alembic - Database migrations
  • WebSockets - Real-time communication
  • JWT - Authentication tokens
  • Python Binance & yfinance - Market data providers

Frontend

  • React 19 - UI library
  • Vite - Build tool and dev server
  • React Router - Client-side routing
  • Axios - HTTP client
  • Tailwind CSS - Utility-first CSS framework
  • Lucide React - Icon library

Infrastructure

  • Docker & Docker Compose - Containerization
  • Nginx - Web server for frontend
  • Uvicorn - ASGI server

📋 Prerequisites

  • Docker and Docker Compose installed
  • Git
  • (Optional) Node.js 20+ and Python 3.10+ for local development

🚦 Getting Started

Using Docker Compose (Recommended)

  1. Clone the repository

    git clone <your-repo-url>
cd crypto-alert

  2. Create environment file (optional)

    # Create .env file in project root
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=crypto_alerts
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-key-here

# Optional: API Keys
BINANCE_API_KEY=your-binance-api-key
BINANCE_API_SECRET=your-binance-api-secret

# Optional: Email configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=your-email@gmail.com

  3. Start all services

    docker-compose up -d

  4. Access the application

  5. View logs

    # All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend
docker-compose logs -f frontend

Stop Services

docker-compose down

Reset Database (⚠️ Deletes all data)

docker-compose down -v
docker-compose up -d

🔧 Configuration

Environment Variables

The application uses environment variables for configuration. You can set them in a .env file or as environment variables in docker-compose.yml.

Required Variables

  • DATABASE_URL - PostgreSQL connection string (auto-generated in docker-compose)
  • SECRET_KEY - Secret key for encryption
  • REDIS_URL - Redis connection string (auto-generated in docker-compose)

Optional Variables

  • POSTGRES_USER - PostgreSQL username (default: postgres)
  • POSTGRES_PASSWORD - PostgreSQL password (default: postgres)
  • POSTGRES_DB - Database name (default: crypto_alerts)
  • CORS_ORIGINS - Comma-separated list of allowed origins
  • SMTP_* - Email configuration for notifications

API Endpoints

All API endpoints are prefixed with /api/v1/.

Authentication (/api/v1/auth)

  • POST /register - Register a new user
  • POST /login - Login and get JWT tokens
  • POST /refresh - Refresh access token
  • GET /me - Get current user info
  • POST /logout - Logout user

Alerts (/api/v1/alerts)

  • POST / - Create a new alert
  • GET / - Get all user alerts
  • GET /{alert_id} - Get specific alert
  • PUT /{alert_id} - Update alert
  • DELETE /{alert_id} - Delete alert

Market Data (/api/v1/market)

  • GET /price/{symbol} - Get current price
  • POST /prices - Get multiple prices
  • GET /validate/{symbol} - Validate symbol exists

WebSocket (/api/v1/ws)

  • WS /connect - Connect for real-time updates

Notifications (/api/v1/notifications)

  • POST /test-email - Send test email

💻 Local Development

Backend Development

cd backend

# Install dependencies using uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Or using pip
pip install -r requirements.txt

# Set up environment variables
export DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/crypto_alerts"
export REDIS_URL="redis://localhost:6379/0"
export SECRET_KEY="your-secret-key"

# Run migrations
alembic upgrade head

# Start development server
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Frontend Development

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

The frontend will run on http://localhost:5173 (or another port if 5173 is busy).

📁 Project Structure

crypto-alert/
├── backend/
│   ├── src/
│   │   ├── auth/          # Authentication logic
│   │   ├── alerts/        # Alert management
│   │   ├── market_data/   # Market data fetching
│   │   ├── notifications/ # Email notifications
│   │   ├── websocket/     # WebSocket handlers
│   │   ├── cache/         # Redis client
│   │   ├── database.py    # Database setup
│   │   ├── config.py      # Configuration
│   │   └── main.py        # FastAPI app
│   ├── alembic/           # Database migrations
│   ├── Dockerfile
│   └── pyproject.toml
├── frontend/
│   ├── src/
│   │   ├── api/           # API client
│   │   ├── contexts/      # React contexts
│   │   ├── pages/         # Page components
│   │   └── App.jsx
│   ├── Dockerfile
│   └── package.json
└── docker-compose.yml

🐛 Troubleshooting

Backend can't connect to database

  • Check that PostgreSQL container is running: docker-compose ps
  • Verify database credentials in environment variables
  • Check logs: docker-compose logs postgres

CORS errors

  • Ensure your frontend URL is in CORS_ORIGINS
  • Check backend logs for CORS-related errors
  • Verify frontend is accessing from allowed origin

Redis connection issues

  • Check Redis container is running: docker-compose logs redis
  • Application will work without Redis (caching disabled)

Frontend shows network errors

  • Verify backend is running and accessible
  • Check browser console for detailed error messages
  • Ensure API base URL is correct in src/api/client.js

🧪 Testing

API documentation and testing interface available at:

📝 Database Migrations

# Create a new migration
docker exec -it crypto-alert-backend alembic revision --autogenerate -m "description"

# Apply migrations
docker exec -it crypto-alert-backend alembic upgrade head

# Rollback migration
docker exec -it crypto-alert-backend alembic downgrade -1

🔐 Security Notes

  • Change default passwords and secrets in production
  • Use strong SECRET_KEY values
  • Enable HTTPS in production
  • Configure proper CORS origins
  • Keep dependencies updated

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

👤 Author

Boluwatife Leke-Oduoye

🙏 Acknowledgments

  • Binance API for cryptocurrency data
  • Yahoo Finance for stock market data