Enterprise-grade price tracking made simple — Monitor product prices across the web and get instant notifications when prices drop.
- 🔍 Smart Price Tracking — Monitor prices from any e-commerce website with flexible CSS selectors
- 📧 Multi-Channel Notifications — Get alerts via email (SMTP) or SMS (Twilio) when prices change
- 📊 Price History — Track price trends and changes over time with detailed history
- 🔒 Enterprise Security — Encryption, CSRF protection, rate limiting, and comprehensive input validation
- 🚀 Production Ready — Docker support, health checks, Prometheus metrics, and structured logging
- 🧪 Well Tested — 80.67% test coverage with comprehensive unit, integration, and security tests
- ⚡ High Performance — Async HTTP client, database connection pooling, and optimized queries
- 📱 Modern Web UI — Clean, responsive interface for managing trackers and profiles
-
Clone the repository
git clone https://github.com/pricewatch/pricewatch.git cd pricewatch -
Create and activate a virtual environment
# Windows python -m venv .venv .venv\Scripts\activate # macOS/Linux python -m venv .venv source .venv/bin/activate
-
Install dependencies
pip install -r requirements.txt
-
Configure environment
# Copy example configuration cp .env.example .env # Edit .env and set at minimum: # SECRET_KEY=your-super-secure-secret-key-minimum-32-characters # DATABASE_URL=sqlite:///pricewatch.db
-
Initialize database
alembic upgrade head
-
Start the application
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
-
Open your browser
http://localhost:8000
🎉 You're all set! Start tracking prices by adding your first tracker.
- Navigate to the home page at
http://localhost:8000 - Click "Add Tracker"
- Enter the product URL (e.g., from Amazon, eBay, or any e-commerce site)
- Optionally specify a CSS selector for the price element
- Choose your notification method (Email or SMS)
- Enter your contact information
- Click "Create Tracker"
- Go to Admin → Profiles
- Click "Create New Profile"
- Configure SMTP settings:
- SMTP Host (e.g.,
smtp.gmail.com) - SMTP Port (usually
587for TLS) - Username and Password
- From Email address
- SMTP Host (e.g.,
- Sign up for Twilio
- Get your Account SID, Auth Token, and Phone Number
- Create a notification profile with your Twilio credentials
- View All Trackers — Main dashboard shows all active trackers
- Edit Tracker — Click any tracker to modify settings
- Delete Tracker — Remove trackers you no longer need
- Manual Refresh — Check for price updates on demand
- Price History — View detailed price change history
Create a .env file in the project root with the following variables:
# Required
SECRET_KEY=your-super-secure-secret-key-minimum-32-characters
DATABASE_URL=sqlite:///pricewatch.db
# Application
ENVIRONMENT=development
DEBUG=true
LOG_LEVEL=INFO
# Security
RATE_LIMIT_PER_MINUTE=60
RATE_LIMIT_BURST=10
ALLOWED_HOSTS=localhost,127.0.0.1
# Scraping
REQUEST_TIMEOUT=30
MAX_RETRIES=3
SCHEDULE_MINUTES=30
USE_ASYNC_CLIENT=false
# SMTP (Optional - for email notifications)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
FROM_EMAIL=your-email@gmail.com
# Twilio (Optional - for SMS notifications)
TWILIO_ACCOUNT_SID=your-twilio-sid
TWILIO_AUTH_TOKEN=your-twilio-token
TWILIO_FROM_NUMBER=your-twilio-number
# Database (Optional - for PostgreSQL/MySQL)
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10
DB_POOL_TIMEOUT=30For production deployments:
- Use PostgreSQL or MySQL instead of SQLite
- Set
ENVIRONMENT=productionandDEBUG=false - Configure proper
ALLOWED_HOSTS - Use a strong, randomly generated
SECRET_KEY - Enable HTTPS with a reverse proxy (nginx)
- Set up proper logging and monitoring
┌─────────────────────────────────────────────────────────────┐
│ Pricewatch v2.1 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Web UI │ │ REST API │ │ Health API │ │
│ │ (Templates) │ │ (FastAPI) │ │ (Monitoring)│ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └───────────────────┼────────────────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ Service Layer │ │
│ ├─────────────────┤ │
│ │ TrackerService │ │
│ │ ProfileService │ │
│ │SchedulerService │ │
│ │NotificationSvc │ │
│ └────────┬────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ │ │ │ │
│ ┌──────▼──────┐ ┌────────▼────────┐ ┌──────▼──────┐ │
│ │ Scraper │ │ Database │ │ Security │ │
│ │ (Price │ │ (SQLAlchemy) │ │ (Encrypt, │ │
│ │ Extraction) │ │ │ │ Validate, │ │
│ └─────────────┘ └─────────────────┘ │ Rate Limit)│ │
│ └─────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ External Services │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ SMTP │ │ Twilio │ │ Web │ │ │
│ │ │ (Email) │ │ (SMS) │ │ Scraping │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────┘
- Service Layer — Business logic separation with
TrackerService,ProfileService,SchedulerService, andNotificationService - Security Layer — Encryption, validation, rate limiting, CSRF protection, and security headers
- Database Layer — SQLAlchemy ORM with Alembic migrations and connection pooling
- Scraping Engine — Flexible price extraction with CSS selectors and async HTTP support
# Run all tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=app --cov-report=html
# Run specific test categories
pytest tests/test_security.py -v # Security tests
pytest tests/test_api.py -v # API endpoint tests
pytest tests/test_services.py -v # Service layer tests
pytest tests/test_scraper.py -v # Scraper tests
pytest tests/test_integration.py -v # Integration tests- Current Coverage: 80.67%
- Minimum Required: 75%
- HTML Report: Generated in
htmlcov/directory
# Generate coverage report
pytest tests/ --cov=app --cov-report=term-missing --cov-fail-under=75# Build the image
docker build -t pricewatch:latest .
# Run the container
docker run -p 8000:8000 --env-file .env pricewatch:latest# Development
docker-compose up -d
# Production
docker-compose -f docker-compose.prod.yml up -dThe Docker setup includes:
- Multi-stage builds for optimized image size
- Non-root user for security
- Health checks
- Resource limits
- Persistent volumes for database
- Basic Health:
http://localhost:8000/health - Detailed Health:
http://localhost:8000/health/detailed - Prometheus Metrics:
http://localhost:8000/metrics - API Documentation:
http://localhost:8000/docs
Pricewatch uses structured JSON logging with:
- Request ID tracking for full request lifecycle
- Configurable log levels (DEBUG, INFO, WARNING, ERROR)
- Sensitive data masking (passwords, tokens automatically redacted)
- Contextual information (user, request, error details)
- 🔐 Encryption at Rest — Sensitive data encrypted using Fernet (Fernet symmetric encryption)
- 🛡️ CSRF Protection — Token-based protection on all forms
- 🚦 Rate Limiting — IP-based rate limiting with automatic cleanup
- ✅ Input Validation — Comprehensive validation with Pydantic schemas
- 🔍 SSRF Protection — URL validation preventing private IP access
- 📋 Security Headers — X-Content-Type-Options, X-Frame-Options, CSP, and more
- 🔑 Request Tracking — Unique request IDs for full observability
| Category | Technology |
|---|---|
| Framework | FastAPI |
| Database | SQLAlchemy + Alembic |
| Validation | Pydantic |
| Scraping | BeautifulSoup4 + httpx |
| Templates | Jinja2 |
| Security | Cryptography |
| Testing | Pytest |
| Linting | Ruff |
| Type Checking | MyPy |
| Monitoring | Prometheus |
pricewatch/
├── app/ # Main application code
│ ├── services/ # Business logic layer
│ ├── static/ # CSS and static assets
│ └── templates/ # HTML templates
├── docs/ # Documentation
│ ├── CHANGELOG.md
│ ├── CONTRIBUTING.md
│ ├── SECURITY.md
│ └── ...
├── tests/ # Test suite
├── migrations/ # Database migrations
├── docker-compose.yml # Docker Compose config
├── Dockerfile # Docker image definition
├── requirements.txt # Python dependencies
├── pyproject.toml # Project configuration
└── README.md # This file
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Add tests for new features
- Ensure all tests pass (
pytest tests/) - Run pre-commit hooks (
pre-commit run --all-files) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please read our Code of Conduct before contributing.
This project is licensed under the MIT License — see the LICENSE file for details.
- Import Errors → Ensure virtual environment is activated
- Database Errors → Run
alembic upgrade head - Port Conflicts → Use different port:
--port 8001 - Permission Errors → Check file permissions
- 📖 Check the Documentation
- 📋 Review the Changelog
- 🔒 Read the Security Policy
- 🐛 Open an Issue
- OAuth2 authentication
- API key management
- Redis caching layer
- Webhook notifications
- Multi-tenant support
- Price prediction algorithms
- Grafana dashboard integration
See docs/IMPROVEMENT_PLAN.md for detailed roadmap.
- FastAPI Community — For excellent documentation and support
- Contributor Covenant — For the Code of Conduct template
- All Contributors — Thank you to everyone who has contributed to Pricewatch!
Made with ❤️ by the Pricewatch Team
⭐ Star us on GitHub • 📖 Documentation • 🐛 Report Bug • 💡 Request Feature