141 lines
5.9 KiB
Markdown
141 lines
5.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**Exchange Data Manager** - Efficiently retrieve and manage financial candlestick data with caching, REST API, and WebSocket support.
|
|
|
|
## ⚠️ CRITICAL: Updating Todos, Milestones, and Goals
|
|
|
|
**DO NOT edit `todos.md`, `milestones.md`, or `goals.md` files directly.**
|
|
|
|
These files are managed by Development Hub which has file watchers and sync logic. Direct edits will be overwritten or cause conflicts.
|
|
|
|
**Use the `devhub-tasks` CLI instead:**
|
|
|
|
```bash
|
|
# Status overview
|
|
devhub-tasks status exchange-data-manager
|
|
|
|
# Add todos
|
|
devhub-tasks todo add exchange-data-manager "Task description" --priority high --milestone M1
|
|
|
|
# Complete todos (by text match or ID number)
|
|
devhub-tasks todo complete exchange-data-manager "Task description"
|
|
devhub-tasks todo complete exchange-data-manager 3
|
|
|
|
# List todos
|
|
devhub-tasks todo list exchange-data-manager
|
|
|
|
# Add milestones
|
|
devhub-tasks milestone add exchange-data-manager M2 --name "Milestone Name" --target "March 2026"
|
|
|
|
# Complete milestones (also completes linked todos)
|
|
devhub-tasks milestone complete exchange-data-manager M1
|
|
|
|
# Goals
|
|
devhub-tasks goal add exchange-data-manager "Goal description" --priority high
|
|
devhub-tasks goal complete exchange-data-manager "Goal description"
|
|
```
|
|
|
|
Use `--json` flag for machine-readable output. Run `devhub-tasks --help` for full documentation.
|
|
|
|
**Files you CAN edit directly:** `overview.md`, `architecture.md`, `README.md`, and any other docs.
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
# Install for development
|
|
pip install -e ".[dev]"
|
|
|
|
# Run tests
|
|
pytest
|
|
|
|
# Run a single test
|
|
pytest tests/test_file.py::test_name
|
|
```
|
|
|
|
## Architecture
|
|
|
|
Three-tier caching system with REST API and WebSocket interfaces:
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ API Layer │
|
|
│ REST (FastAPI) WebSocket (websockets) │
|
|
└────────────────────────────┬────────────────────────────────┘
|
|
│
|
|
┌────────────────────────────▼────────────────────────────────┐
|
|
│ Cache Manager │
|
|
│ Request → Memory → Database → Exchange → Save → Return │
|
|
└────────────────────────────┬────────────────────────────────┘
|
|
│
|
|
┌────────────────────────────▼────────────────────────────────┐
|
|
│ Exchange Connectors │
|
|
│ Binance │ KuCoin │ Kraken │ ... │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Key Modules
|
|
|
|
| Module | Purpose |
|
|
|--------|---------|
|
|
| `main.py` | Entry point, starts REST server |
|
|
| `config.py` | Configuration loading from YAML |
|
|
| `api/rest.py` | FastAPI REST endpoints |
|
|
| `api/websocket.py` | WebSocket server for real-time updates |
|
|
| `cache/manager.py` | Core cache logic (memory → db → exchange) |
|
|
| `cache/memory.py` | In-memory LRU cache with TTL |
|
|
| `cache/database.py` | Synchronous SQLite operations |
|
|
| `cache/async_database.py` | Async SQLite operations for candle persistence |
|
|
| `cache/connection_pool.py` | Database connection pooling |
|
|
| `cache/gaps.py` | Gap detection in candle data |
|
|
| `cache/gap_filler.py` | Gap filling logic |
|
|
| `cache/completeness.py` | Completeness tracking for data ranges |
|
|
| `exchanges/base.py` | Abstract exchange connector interface |
|
|
| `exchanges/ccxt_connector.py` | CCXT-based connector (supports 100+ exchanges) |
|
|
| `exchanges/binance.py` | Binance-specific connector (legacy, WebSocket support) |
|
|
| `candles/assembler.py` | Builds candles from trade ticks |
|
|
| `candles/models.py` | Candle data models and validation |
|
|
| `sessions/manager.py` | Session management for connections |
|
|
| `sessions/models.py` | Session data models |
|
|
| `monitoring/health.py` | Health check endpoints and system status |
|
|
| `monitoring/metrics.py` | Performance metrics tracking |
|
|
| `utils/timeframes.py` | Timeframe utilities and conversions |
|
|
| `utils/timestamps.py` | Timestamp utilities |
|
|
|
|
**Note:** KuCoin, Kraken, and 100+ other exchanges are supported via `CCXTConnector` - use `create_connector("exchange_name")` from `exchanges/__init__.py`.
|
|
|
|
### Key Paths
|
|
|
|
- **Source code**: `src/exchange_data_manager/`
|
|
- **Tests**: `tests/`
|
|
- **Configuration**: `config.yaml`
|
|
- **Database**: `data/candles.db`
|
|
- **Documentation**: `docs/` (symlink to project-docs)
|
|
|
|
### Running the Service
|
|
|
|
```bash
|
|
# Start the service
|
|
python -m exchange_data_manager
|
|
|
|
# Or with uvicorn for development
|
|
uvicorn exchange_data_manager.api.rest:app --reload --port 8080
|
|
```
|
|
|
|
## Documentation
|
|
|
|
Documentation lives in `docs/` (symlink to centralized docs system).
|
|
|
|
**Before updating docs, read `docs/updating-documentation.md`** for full details on visibility rules and procedures.
|
|
|
|
Quick reference:
|
|
- Edit files in `docs/` folder
|
|
- Use `public: true` frontmatter for public-facing docs
|
|
- Use `<!-- PRIVATE_START -->` / `<!-- PRIVATE_END -->` to hide sections
|
|
- Deploy: `~/PycharmProjects/project-docs/scripts/build-public-docs.sh exchange-data-manager --deploy`
|
|
|
|
Do NOT create documentation files directly in this repository.
|