# 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 |
| `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/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 implementation |
| `exchanges/binance.py` | Binance connector |
| `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 |
| `utils/timeframes.py` | Timeframe utilities and conversions |
| `utils/timestamps.py` | Timestamp utilities |

**Planned (M2):** `api/websocket.py`, `exchanges/kucoin.py`, `exchanges/kraken.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.