btc-trading/GEMINI.md

Gemini Context: BTC Trading Dashboard

This project is a Bitcoin trading platform and automated bot system. It features a FastAPI backend, a real-time data collector, a PostgreSQL (TimescaleDB) database, and an interactive HTML/JS dashboard for technical analysis and strategy visualization.

Project Overview

• Purpose: Real-time BTC data collection, technical indicator computation, and trading strategy execution/backtesting.
• Core Technologies:
  • Backend: Python 3.9+ with FastAPI.
  • Frontend: Vanilla HTML/JS with lightweight-charts.
  • Database: PostgreSQL with TimescaleDB extension for time-series optimization.
  • Infrastructure: Docker & Docker Compose.
• Architecture:
  • data_collector: Handles WebSocket data ingestion and custom timeframe generation.
  • api_server: Serves the dashboard and REST API for candle/indicator data.
  • indicator_engine: Computes SMA, EMA, and specialized HTS indicators.
  • strategies: Contains trading logic (e.g., Ping Pong bot, HTS strategy).

Building and Running

Local Setup

1. Environment:

   python -m venv venv
   source venv/bin/activate  # venv\Scripts\activate on Windows
   pip install -r requirements.txt
   

2. Configuration: Create a .env file based on the project's requirements (see README.md).
3. Database Test: python test_db.py
4. Run API Server: uvicorn src.api.server:app --reload --host 0.0.0.0 --port 8000

Docker Deployment

• Commands:
  • docker-compose up -d (from the docker/ directory or root depending on setup).
• Services: timescaledb, data_collector, api_server, ping_pong_bot.

Key Files and Directories

• src/api/server.py: FastAPI entry point and REST endpoints.
• src/data_collector/main.py: Data collection service logic.
• src/data_collector/indicator_engine.py: Technical indicator calculations (stateless math).
• src/api/dashboard/static/: Frontend assets (HTML, CSS, JS).
• src/strategies/: Directory for trading strategy implementations.
• HTS_STRATEGY.md: Detailed documentation for the "Higher Timeframe Trend System" strategy.
• AGENTS.md: Specific coding guidelines and standards for AI agents.

Development Conventions

Python Standards

• Style: Follow PEP 8; use Type Hints consistently.
• Documentation: Use Google-style docstrings for all public functions and classes.
• Asynchrony: Use async/await for all database (via asyncpg) and network operations.
• Validation: Use Pydantic models for data validation and settings.

Frontend Standards

• Tech: Vanilla CSS (Avoid Tailwind unless requested) and Vanilla JS.
• Location: Static files reside in src/api/dashboard/static/.

AI Coding Guidelines (from AGENTS.md)

• Organization: Place new code in corresponding modules (api, data_collector, strategies).
• Error Handling: Use explicit exceptions; log errors with context; never suppress silently.
• Security: Protect credentials; use environment variables; validate all inputs.

Strategy: HTS (Higher Timeframe Trend System)

The project emphasizes the HTS strategy, which uses fast (33) and slow (144) RMA channels to identify trends. Key rules include price position relative to Red (Slow) and Aqua (Fast) channels, and a 1H Red Zone filter for long trades. Refer to HTS_STRATEGY.md for full logic.