# 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**:
   ```bash
   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.