116 lines
4.7 KiB
Markdown
116 lines
4.7 KiB
Markdown
# Project Overview
|
|
|
|
Algorithmic trading bot platform with WebSocket-based real-time orderbook and trade data collection from multiple cryptocurrency exchanges. Uses TimescaleDB for archival, Redis for caching/messaging, and Celery for background tasks. Designed for momentum trading strategies with slippage prediction and dynamic trade execution across spot and futures markets.
|
|
|
|
## Repository Structure
|
|
|
|
- `docs/` - Documentation directory for architectural decisions and design notes
|
|
- `modules/` - Python modules containing core functionality
|
|
- `prompts/` - Visual diagrams and project documentation files
|
|
- `tests/` - Test suite for validation
|
|
- `requirements.txt` - Python dependencies list
|
|
- `Makefile` - Build and development task automation
|
|
- `README.rst` - Project overview
|
|
|
|
## Build & Development Commands
|
|
|
|
```bash
|
|
# Install dependencies
|
|
make init
|
|
|
|
# Run tests (currently stub - to be implemented)
|
|
make test
|
|
|
|
# Debug (future - see TODO: add pytest with debug flags or pdb integration)
|
|
```
|
|
|
|
## Code Style & Conventions
|
|
|
|
Use Python typing (type hints for all functions), PEP 8 style guide, and module docstrings for clarity.
|
|
|
|
Naming: kebab-case for modules, snake_case for files, PascalCase for classes, camelCase for methods/variables.
|
|
|
|
Environment variables in `.env` file (never commit secrets). Use environment-based configuration.
|
|
|
|
Commit message format: `<type>: <description>` where type is one of (feat, fix, docs, refactor, test, chore).
|
|
|
|
## Architecture Notes
|
|
|
|
```
|
|
+-------------------+ +------------------+
|
|
| Exchange | |Exchange REST API |
|
|
| WebSocket APIs | | trade endpoints |
|
|
| (Binance,OKX,etc.)| |(set/cancel trade)|
|
|
+-------------------+ +------------------+
|
|
| ^
|
|
v |
|
|
+-------------------+ |
|
|
| WebSocket Clients | |
|
|
| (real-time data) | |
|
|
+-------------------+ |
|
|
| |
|
|
v |
|
|
+-------------------+ +------------------+
|
|
| Redis | ---> | Celery Workers |
|
|
|(Msg broker/Cache) | | (Processors) |
|
|
+-------------------+ +------------------+
|
|
^ |
|
|
| v
|
|
| +-------------------+
|
|
+------------------ | TimescaleDB |
|
|
| (Archive) |
|
|
+-------------------+
|
|
```
|
|
|
|
**Data Flow**: Exchanges push real-time WebSocket messages to event handlers. Handlers publish events to Redis for Celery workers to consume. Workers process data, update archives in TimescaleDB, and trigger real-time strategy inference. Celery workers handle backtesting on historical data and trade execution.
|
|
|
|
**Key Components**:
|
|
- Exchange adapters: Uniform WebSocket handling for Binance/OKX/etc., minimizing exchange-specific logic
|
|
- Event handlers: Parse orderbook/trade events, implement reconnection/backoff
|
|
- Strategy engine: Momentum analysis, slippage prediction, order concentration detection
|
|
- Celery workers: Background data persistence, backtesting, trade execution coordination
|
|
- TimescaleDB: Time-series data storage for analysis and replaying
|
|
- Redis: In-memory cache and message queue infrastructure
|
|
|
|
## Testing Strategy
|
|
|
|
Unit tests with pytest to test individual exchange adapters, event handlers, and strategy functions.
|
|
|
|
Integration tests verify Redis/TimescaleDB/Celery workflow with test fixtures.
|
|
|
|
TODO: Add CI/CD pipeline configuration and test coverage reporting (coverage.py + SonarQube).
|
|
|
|
Test data should be mock WebSocket responses for unit tests; real market data for integration tests with rate limiting.
|
|
|
|
## Security & Compliance
|
|
|
|
> TODO: Define and document API key handling strategy (encrypted environment variables, vault integration).
|
|
|
|
> TODO: Implement dependency scanning with Snyk or similar.
|
|
|
|
> TODO: Define data retention policies and privacy considerations.
|
|
|
|
## Agent Guardrails
|
|
|
|
**Never touch**:
|
|
- Financial trading keys or secrets
|
|
- Dockerfile or Kubernetes deployment manifests until production ready
|
|
- CI/CD pipeline configuration files
|
|
|
|
**Required reviews**:
|
|
- PRs modifying core exchange adapters MUST be reviewed by lead engineer
|
|
- Changes to strategy logic require trading strategy team sign-off
|
|
- Any security-sensitive code requires security review
|
|
|
|
## Extensibility Hooks
|
|
|
|
- `SUPPORTED_EXCHANGES` environment variable to configure supported exchanges.
|
|
- `REDIS_URL` and `TIMESCALEDB_URL` for cache and database connection configuration
|
|
- Strategy implementations exported via `strategy_registry` dictionary for plugin loading
|
|
- Celery broker url and backend configurable via environment variables
|
|
|
|
## Further Reading
|
|
|
|
> TODO: Create docs/ARCH.md for detailed architecture
|
|
> TODO: Add detailed API documentation in docs/API.md
|