feat: .env.example and AGENTS.md

2026-03-06 17:36:36 +05:00
parent c7dccf7796
commit f9f783d885
5 changed files with 562 additions and 3 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,115 @@
+# 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