🎉 This project uses NX for monorepo management!
Quick Start:
npm install # Install all dependencies with prerequisite checks npm run dev # Start development (frontend + backend)
Alpaca API Wrapper is a Django-based starter project for building your own stock market analysis tools, backtesting engines, or trading bots. It leverages the Alpaca API for real-time market data and provides a full-stack, Dockerized environment.
Use it as a foundation for backtesting, live-trading bots, research notebooks, or data pipelines—with built-in support for watchlists, historical and real-time data, and a dedicated WebSocket service for streaming market data.
🌐 Try the live demo: https://alpaca.mnaveedk.com/
- Alpaca API Wrapper
| Category | What you get |
|---|---|
| Watchlists | Create watchlists, add assets, and manage your market focus |
| Historical Data | Assets in watchlists fetch and cache historical OHLCV data automatically |
| Real-Time Data | Assets in watchlists are subscribed to real-time Alpaca market feeds |
| WebSocket Service | Dedicated Django management command runs in its own container, handling |
| real-time tick processing and candle aggregation (1m and higher timeframes) | |
| Interactive Analysis | Access and experiment with real-time and historical data for your watchlists |
| Session management | Secure session generation with your API key & secret |
| Task orchestration | Celery + Redis for async jobs & scheduling |
| Dockerised stack | docker compose up and you're done |
| Layer | Tech |
|---|---|
| Monorepo | NX · npm workspaces |
| Backend | Django · Django REST Framework |
| Async / broker | Celery · Redis |
| Realtime | Django Channels (WebSockets) |
| Frontend | React · Vite |
| Database | PostgreSQL |
| Container / infra | Docker · Docker Compose |
| Dev tooling | uv (deps) · black (format) · ruff (lint) · pytest (tests) · vitest (FE tests) · Smart setup scripts |
| Service | Purpose | Port | Environment | Notes |
|---|---|---|---|---|
| NX | Monorepo orchestration | N/A | Local | Task runner, caching, parallelization |
| Frontend | React SPA (Vite) | 5173 | Local | Hot module replacement enabled |
| Backend | Django API + WebSockets | 8000 | Docker | ASGI server with Channels |
| PostgreSQL | Primary database | 5432 | Docker | Persistent data storage |
| Redis | Cache + Message broker | 6379 | Docker | Celery task queue |
| Celery Workers | Background tasks | N/A | Docker | Async job processing |
| Celery Beat | Task scheduler | N/A | Docker | Periodic task execution |
| WebSocket | Real-time data stream | N/A | Docker | Market data WebSocket service |
| Flower | Task monitoring | 5555 | Docker | Celery dashboard |
Infrastructure services (backend, db, cache, broker, workers, beat, websocket, flower) are in
docker-compose.yml.
Frontend runs locally via NX for fast hot reload. NX orchestrates all tasks across the monorepo with smart prerequisite checking.
- Node.js (v18 or higher) & npm installed
- Docker & Docker Compose installed
- uv (Python package installer) installed
- An Alpaca API key & secret
- Create a
.envs/.envfile with your API credentials
Note: The setup will automatically check for all prerequisites and guide you through any missing requirements.
git clone https://github.com/naveedkhan1998/alpaca-main.git
cd alpaca-main
# Install everything automatically (NX + Frontend + Backend)
npm installWhat happens during installation:
- ✅ Checks for Node.js, Docker, and uv installation
- ✅ Validates Alpaca API credentials in
.envs/.env - ✅ Installs NX monorepo tooling
- ✅ Installs frontend dependencies (~768 packages)
- ✅ Installs and syncs backend dependencies (~72 Python packages)
- ✅ Creates setup completion marker
Note: If any prerequisites are missing, the installation will stop and provide clear instructions on what to install.
# Install everything automatically
npm install
# Start all services (frontend + backend infrastructure)
npm run devThis single command will:
- 🚀 Start the frontend Vite dev server (with hot reload)
- 🐳 Start Docker infrastructure (PostgreSQL, Redis, Backend API, Celery, WebSocket, Flower)
- ⚡ Run both in parallel automatically via NX
Note:
npm installincludes prerequisite checks and will guide you if anything is missing.
# Frontend only (requires backend infrastructure running)
npm run dev:frontend
# Backend infrastructure only
npm run dev:backend
# Or manually start Docker services
npm run docker:upOnce everything is running, you can access:
- Frontend Application: http://localhost:5173 — React SPA with Vite HMR
- Backend API: http://localhost:8000 — Django REST API
- Django Admin: http://localhost:8000/admin — Admin interface
- Celery Flower: http://localhost:5555 — Task monitoring dashboard
Note: Frontend runs locally with Vite for fast hot reload. Backend services run in Docker for consistency.
All commands run via NX for intelligent caching and parallel execution:
# Development
npm run dev # Start both frontend + backend
npm run dev:frontend # Frontend only
npm run dev:backend # Backend only
# Code Quality
npm run lint # Lint both projects
npm run lint:fix # Lint and auto-fix both projects
npm run format # Format both projects
npm run format:check # Check formatting without changes
# Testing
npm run test # Test both projects
npm run test:coverage # Test both with coverage reports
# Database Management
npm run makemigrations # Make migrations in Docker container
npm run makemigrations:local # Make migrations locally (faster for development)
npm run migrate # Apply migrations in Docker container
# Docker Management
npm run docker:up # Start Docker services
npm run docker:down # Stop Docker services
npm run docker:logs # View Docker logs
npm run docker:clean # Clean Docker volumes
npm run backend:shell # Shell into backend Docker container
# Build
npm run build # Build frontend for production- Frontend: Vite dev server with instant HMR (Hot Module Replacement)
- Backend: Code mounted as Docker volume, auto-reloads on changes
For faster development iterations, use local migration commands:
# Make migrations locally (faster than Docker)
npm run makemigrations:local
# Apply migrations in container
npm run migrateTip: Use
makemigrations:localduring development for quicker feedback, thenmigrateto apply in the container.
# All tests with NX caching
npm run test
# Tests with coverage reports
npm run test:coverageTip: NX caches test results. Only changed projects and their dependents will re-run tests!
# all workers
docker compose exec backend tail -f /var/log/celery/w*.log# install once on the host
sudo apt-get install multitail # or yum install multitail
# split‑screen log view
docker compose exec backend multitail /var/log/celery/w1.log /var/log/celery/w2.logOpen http://localhost:5555 in your browser for task‑level visibility.
Tip: Configure log‑rotation (
logrotate) inside the container—or mount/var/log/celeryto your host—to keep log sizes under control.
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and ensure tests pass
- Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- Follow the existing code style (we use
blackfor Python andprettierfor JavaScript) - Add tests for new features
- Update documentation as needed
- Ensure all tests pass before submitting
Found a bug or have a feature request? Please open an issue with:
- Clear description of the problem or feature
- Steps to reproduce (for bugs)
- Expected vs actual behavior
- Your environment details
This project is licensed under the MIT License - see the LICENSE file for details.
- ✅ Use - Use the software for any purpose
- ✅ Modify - Change the software to suit your needs
- ✅ Distribute - Share the software with others
- ✅ Commercial use - Use the software for commercial purposes
- ❗ Include license - Include the original license when distributing
This project wouldn't be possible without these amazing technologies and resources:
- Alpaca API - The financial data API that powers this wrapper
- NX - Smart monorepo build system with intelligent caching and task orchestration
- Django & Django REST Framework - Web framework and API toolkit
- Django Channels - WebSocket support for Django
- Celery - Distributed task queue
- Redis - In-memory data structure store
- PostgreSQL - Powerful, open source object-relational database
- React & Vite - Frontend framework and build tool
- Docker & Docker Compose - Containerization platform
- npm workspaces - Monorepo package management
- uv - Fast Python package installer
- Black - Python code formatter
- Ruff - Fast Python linter
- pytest - Python testing framework
- Vitest - Vite-native testing framework
- The open source community for creating and maintaining these incredible tools
- All contributors who have helped improve this project
Disclaimer: This project is not affiliated with Alpaca Markets. Use at your own risk and ensure compliance with Alpaca's terms of service.
Naveed Khan
📧 Email: [email protected]
🐙 GitHub: naveedkhan1998
🌐 Website: mnaveedk.com
docker compose -f docker-compose.yaml -f docker-compose.local.yaml up -d
Happy hacking & good trades! 🚀