btc-trading/AGENTS.md

# Agent Development Guidelines

## Project Overview
This is a Bitcoin trading dashboard with FastAPI backend, PostgreSQL database, and technical analysis features. The system consists of:
- Backend: FastAPI (Python 3.9+)
- Frontend: HTML/JS dashboard with lightweight-charts
- Database: PostgreSQL (TimescaleDB optimized)
- Features: Real-time candle data, technical indicators (SMA, EMA, RSI, MACD, Bollinger Bands), trading strategy simulation, backtesting

## Build/Lint/Test Commands

### Setup
```bash
# Create and activate virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
# or source venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt
```

### Running Development Server
```bash
# Quick start (Windows)
start_dev.cmd

# Quick start (Linux/Mac)
chmod +x start_dev.sh
./start_dev.sh

# Manual start
uvicorn src.api.server:app --reload --host 0.0.0.0 --port 8000
```

### Testing
```bash
# Test database connection
python test_db.py

# Run single test (no existing test framework found but for any future tests)
python -m pytest <test_file>.py::test_<function_name> -v
```

### Environment Setup
Environment variables in `.env` file:
```
DB_HOST=20.20.20.20
DB_PORT=5433
DB_NAME=btc_data
DB_USER=btc_bot
DB_PASSWORD=your_password
```

## Code Style Guidelines

### Python Standards
- Follow PEP 8 style guide
- Use type hints consistently throughout
- Module names should be lowercase with underscores
- Class names should use PascalCase
- Function and variable names should use snake_case
- Constants should use UPPER_CASE
- All functions should have docstrings
- Use meaningful variable names (avoid single letter names except for loop counters)

### Imports
- Group imports in order: standard library, third-party, local
- Use relative imports for internal modules
- Sort imports alphabetically within each group

### Error Handling
- Use explicit exception handling with specific exceptions
- Log errors with appropriate context
- Don't suppress exceptions silently
- Use try/except/finally blocks for resource management

### Naming Conventions
- Classes: PascalCase
- Functions and variables: snake_case
- Constants: UPPER_CASE
- Private methods: _private_method
- Protected attributes: _protected_attribute

### Documentation
- All public functions should have docstrings in Google style format
- Class docstrings should explain the class purpose and usage
- Complex logic should be commented appropriately
- API endpoints should be documented in docstrings
- Use inline comments for complex operations

### Data Processing
- Use async/await for database operations
- Handle database connection pooling properly
- Validate incoming data before processing
- Use pydantic models for data validation
- Ensure proper timezone handling for datetime operations

### Security
- Never log sensitive information (passwords, tokens)
- Use environment variables for configuration
- Validate all input data
- Use prepared statements for database queries to prevent injection

### Asynchronous Programming
- Use asyncio for concurrent database operations
- Use async context managers for resource management
- Implement timeouts for database operations
- Handle task cancellation appropriately

### Configuration
- Use pydantic-settings for configuration management
- Load environment variables with python-dotenv
- Provide default values for configuration settings

### Logging
- Use logging module with appropriate log levels (DEBUG, INFO, WARNING, ERROR)
- Include contextual information in log messages
- Use structured logging where appropriate
- Log exceptions with traceback information

### Testing
- Write unit tests for core components
- Test database operations asynchronously
- Mock external services where appropriate
- Test both success and failure cases
- Ensure tests are isolated

## AI Coding Agent Rules

### File Structure and Organization
- Organize code into logical modules: api, data_collector, strategies, etc.
- Use consistent naming across the codebase
- Follow existing project conventions when adding new features
- Place new code in corresponding directories (src/strategies/ for strategies)

### Code Quality
- Maintain clean, readable code
- Write efficient code with good performance characteristics
- Follow existing code patterns for consistency
- Ensure proper error handling in all code paths
- Use type hints and validate with mypy when applicable

### Documentation
- Update docstrings when modifying functions or classes
- Add usage comments for complex logic
- Update README.md if adding major new features
- Document any new environment variables or configuration options

### Integration 
- Respect existing patterns for API endpoints and database access
- Follow established data flow patterns
- Ensure compatibility with existing code when making changes
- Maintain backward compatibility for public APIs

### Dependencies
- Only add dependencies to requirements.txt when necessary
- Check for conflicts with existing dependencies
- Keep dependency versions pinned to avoid breaking changes
- Avoid adding heavyweight dependencies unless truly required