5.1 KiB
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.
┌─────────────────────────────────────────────────────────────────┐
│ Flask + SocketIO │
│ (app.py) │
├─────────────────────────────────────────────────────────────────┤
│ BrighterTrades │
│ (Main application facade/coordinator) │
├─────────┬─────────┬─────────┬─────────┬─────────┬──────────────┤
│ Users │Strategies│ Trades │Indicators│Backtester│ Exchanges │
├─────────┴─────────┴─────────┴─────────┴─────────┴──────────────┤
│ 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 |
Individual strategy execution context |
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 |
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: truefrontmatter 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.