149 lines
6.3 KiB
Markdown
149 lines
6.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**Brighter Trading** - Cryptocurrency trading platform with Blockly-based strategy builder
|
|
|
|
## ⚠️ 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 brightertrading
|
|
|
|
# Add todos
|
|
devhub-tasks todo add brightertrading "Task description" --priority high --milestone M1
|
|
|
|
# Complete todos (by text match or ID number)
|
|
devhub-tasks todo complete brightertrading "Task description"
|
|
devhub-tasks todo complete brightertrading 3
|
|
|
|
# List todos
|
|
devhub-tasks todo list brightertrading
|
|
|
|
# Add milestones
|
|
devhub-tasks milestone add brightertrading M2 --name "Milestone Name" --target "March 2026"
|
|
|
|
# Complete milestones (also completes linked todos)
|
|
devhub-tasks milestone complete brightertrading M1
|
|
|
|
# Goals
|
|
devhub-tasks goal add brightertrading "Goal description" --priority high
|
|
devhub-tasks goal complete brightertrading "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
|
|
|
|
Flask web application with SocketIO for real-time communication, using eventlet for async operations. Features a Blockly-based visual strategy builder frontend with a **unified broker abstraction** supporting backtest, paper, and live trading modes.
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Flask + SocketIO │
|
|
│ (app.py) │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ BrighterTrades │
|
|
│ (Main application facade/coordinator) │
|
|
├─────────┬─────────┬─────────┬─────────┬─────────┬──────────────┤
|
|
│ Users │Strategies│ Trades │Indicators│Backtester│ Exchanges │
|
|
├─────────┴─────────┴─────────┴─────────┴─────────┴──────────────┤
|
|
│ Broker Abstraction │
|
|
│ (BaseBroker → Paper / Backtest / Live brokers) │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ DataCache │
|
|
│ (In-memory caching + SQLite) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Key Modules
|
|
|
|
| Module | Purpose |
|
|
|--------|---------|
|
|
| `app.py` | Flask web server, SocketIO handlers, HTTP routes |
|
|
| `BrighterTrades.py` | Main application facade, coordinates all subsystems |
|
|
| `Strategies.py` | Strategy CRUD operations and execution management |
|
|
| `StrategyInstance.py` | Base strategy execution context |
|
|
| `paper_strategy_instance.py` | Paper trading strategy instance |
|
|
| `backtest_strategy_instance.py` | Backtest strategy instance |
|
|
| `live_strategy_instance.py` | Live trading strategy instance with circuit breaker and position limits |
|
|
| `PythonGenerator.py` | Generates Python code from Blockly JSON |
|
|
| `backtesting.py` | Strategy backtesting engine (uses backtrader) |
|
|
| `indicators.py` | Technical indicator calculations |
|
|
| `candles.py` | Candlestick/OHLCV data management |
|
|
| `trade.py` | Trade lifecycle management |
|
|
| `ExchangeInterface.py` | Multi-exchange interface |
|
|
| `Exchange.py` | Single exchange wrapper (uses ccxt) |
|
|
| `DataCache_v3.py` | In-memory caching with database persistence |
|
|
| `Database.py` | SQLite database operations |
|
|
| `Users.py` | User authentication and session management |
|
|
| `Signals.py` | Trading signal definitions and state tracking |
|
|
| `health.py` | Application health checks |
|
|
| `logging_config.py` | Centralized logging configuration |
|
|
|
|
### Broker Module (`src/brokers/`)
|
|
|
|
| Module | Purpose |
|
|
|--------|---------|
|
|
| `base_broker.py` | Abstract broker interface (BaseBroker) |
|
|
| `paper_broker.py` | Simulated trading with virtual balance |
|
|
| `backtest_broker.py` | Historical data backtesting |
|
|
| `live_broker.py` | Real exchange trading via ccxt |
|
|
| `factory.py` | Creates appropriate broker based on mode |
|
|
|
|
### Key Paths
|
|
|
|
- **Source code**: `src/`
|
|
- **Tests**: `tests/`
|
|
- **Configuration**: `config.yml`
|
|
- **Database**: `BrighterTrading.db` (SQLite)
|
|
- **Documentation**: `docs/` (symlink to project-docs)
|
|
|
|
### Running the Application
|
|
|
|
```bash
|
|
# Start the development server
|
|
cd src && python app.py
|
|
|
|
# Or from project root
|
|
python src/app.py
|
|
```
|
|
|
|
The application runs on `http://127.0.0.1:5002` by default.
|
|
|
|
## 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 brightertrading --deploy`
|
|
|
|
Do NOT create documentation files directly in this repository.
|