# 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