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

   • Frontend: http://localhost (or http://localhost:3000)
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs
   • Health Check: http://localhost:8000/health

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:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

📝 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