7.8 KiB

Raw Blame History

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:

# 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

# 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
`Configuration.py`	Settings management with YAML persistence
`backtest_result.py`	Backtest result schema (dataclasses)
`mapped_strategy.py`	Backtrader strategy integration
`shared_utilities.py`	Time/date conversion utilities
`utils.py`	JSON serialization helpers
`exchange_validation.py`	Exchange requirements validation with structured error codes

EDM Client Module (`src/edm_client/`)

Module	Purpose
`client.py`	REST client for Exchange Data Manager service
`websocket_client.py`	WebSocket client for real-time candle data
`models.py`	Data models (Candle, Subscription, EdmConfig)
`exceptions.py`	EDM-specific exceptions

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

Wallet Module (`src/wallet/`)

Bitcoin wallet system for strategy fees with two-address custody model.

Module	Purpose
`wallet_manager.py`	Main wallet operations, credits ledger, fee accumulation/settlement
`bitcoin_service.py`	Bitcoin key generation, transaction creation, address validation
`encryption.py`	Versioned key encryption for stored private keys
`background_jobs.py`	Deposit detection, withdrawal processing, auto-sweep jobs

Key concepts:

Fee Address: Platform-controlled address for strategy fees (private key stored encrypted)
Sweep Address: User-controlled address for excess funds (we only store public address)
Credits Ledger: Internal balance for instant, reliable strategy fee deduction
Balance Cap: ~$50 limit before auto-sweep to user's sweep address

Key Paths

Source code: src/
Tests: tests/
Configuration: config.yml
Database: BrighterTrading.db (SQLite)
Documentation: docs/ (symlink to project-docs)

Running the Application

# 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  /  to hide sections
Deploy: ~/PycharmProjects/project-docs/scripts/build-public-docs.sh brightertrading --deploy

Do NOT create documentation files directly in this repository.

7.8 KiB Raw Blame History