exchange-data-manager/CLAUDE.md

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:

# 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

# 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

# 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.