# 🏗️ Project Structure

**Complete directory structure and file organization for the Hyperliquid Trading Bot**

## 📁 Directory Overview

```
trader_hyperliquid/
├── 📂 src/                     # Source code
│   ├── 🐍 telegram_bot.py     # Main Telegram bot
│   ├── 🔗 hyperliquid_client.py # Hyperliquid API client
│   ├── ⚙️ config.py           # Configuration management
│   ├── 📊 trading_stats.py    # Statistics tracking
│   ├── 🔔 alarm_manager.py    # Price alarm management
│   └── 📝 logging_config.py   # Logging configuration
├── 📂 tests/                   # Test suite
│   ├── 📋 README.md           # Test documentation
│   ├── 🏃 run_all_tests.py    # Test runner
│   ├── 🧪 test_config.py      # Configuration tests
│   ├── 💰 test_balance.py     # Balance tests
│   ├── 📈 test_perps_commands.py # Trading tests
│   ├── 🚪 test_exit_command.py # Exit command tests
│   └── 📋 test_order_management.py # Order management tests
├── 📂 docs/                    # Documentation
│   ├── 📚 README.md           # Documentation index
│   ├── 📝 commands.md         # Command reference
│   ├── 🚀 setup.md            # Setup guide
│   ├── 🏗️ project-structure.md # This file
│   ├── 🚀 deployment.md       # Deployment guide
│   └── 🔧 SYSTEM_INTEGRATION.md # System integration
├── 📂 config/                  # Configuration files
│   └── 📄 .env.example        # Environment template
├── 📂 logs/                    # Log files (auto-created)
├── 📂 utils/                   # Utility scripts
│   ├── 🔍 get_telegram_chat_id.py # Chat ID finder
│   ├── 🔍 simple_chat_id.py   # Alternative chat ID finder
│   └── 📊 demo_stats.py       # Demo statistics
├── 📂 __pycache__/            # Python cache (auto-created)
├── 📂 venv/                   # Virtual environment
├── 📄 README.md               # Main project README
├── 📄 requirements.txt        # Python dependencies
├── 📄 .gitignore             # Git ignore rules
├── 📄 .env                    # Environment configuration
├── 📊 trading_stats.json      # Persistent statistics data
└── 🚀 trading_bot.py          # Main entry point
```

## 📝 Core Source Files

### **🐍 src/telegram_bot.py**
**Main Telegram bot implementation**
- Telegram bot interface
- Command handlers (/start, /balance, /long, /short, etc.)
- Callback query handling
- Message formatting
- Safety confirmations
- Mobile-optimized interface

**Key Classes:**
- `TelegramTradingBot` - Main bot class

**Key Methods:**
- `start_command()` - Bot startup
- `long_command()` - Long position with stop loss support
- `short_command()` - Short position with stop loss support
- `exit_command()` - Close positions
- `orders_command()` - Order management
- `coo_command()` - Cancel orders
- `sl_command()` - Manual stop loss
- `tp_command()` - Take profit orders
- `alarm_command()` - Price alerts
- `monitoring_command()` - System status
- `performance_command()` - Token performance
- `risk_command()` - Risk metrics
- `version_command()` - System info
- `logs_command()` - Log management
- `balance_adjustments_command()` - Deposit/withdrawal history

### **🔗 src/hyperliquid_client.py**
**Hyperliquid API client using CCXT**
- Exchange connectivity
- Order management
- Balance fetching
- Position tracking
- Market data
- Error handling

**Key Classes:**
- `HyperliquidClient` - API wrapper

**Key Methods:**
- `get_balance()` - Fetch account balance
- `get_positions()` - Get open positions
- `get_open_orders()` - Fetch orders
- `place_market_order()` - Market orders
- `place_limit_order()` - Limit orders
- `cancel_order()` - Cancel orders

### **⚙️ src/config.py**
**Configuration management**
- Environment variable loading
- Validation
- Default settings
- Security handling

**Key Classes:**
- `Config` - Configuration manager

**Key Methods:**
- `validate()` - Validate settings
- `get_hyperliquid_config()` - CCXT config

### **📊 src/trading_stats.py**
**Trading statistics and performance tracking**
- Trade logging
- Performance metrics
- Risk analysis
- JSON persistence

**Key Classes:**
- `TradingStats` - Statistics manager

**Key Methods:**
- `record_trade()` - Log trades
- `get_basic_stats()` - Basic metrics
- `format_stats_message()` - Telegram formatting

### **🔔 src/alarm_manager.py**
**Price alarm management system**
- Price alert creation and monitoring
- Trigger detection
- Alarm persistence
- Multi-token support

**Key Classes:**
- `AlarmManager` - Alarm management

**Key Methods:**
- `create_alarm()` - Create price alert
- `check_alarms()` - Monitor prices
- `remove_alarm()` - Delete alarm
- `get_statistics()` - Alarm stats

### **📝 src/logging_config.py**
**Centralized logging configuration**
- Log level management
- File rotation
- Format standardization
- Cleanup utilities

**Key Functions:**
- `setup_logging()` - Initialize logging
- `cleanup_logs()` - Remove old logs
- `format_log_stats()` - Log statistics

## 🧪 Test Suite

### **🏃 tests/run_all_tests.py**
**Test runner for all test modules**
- Auto-discovery of test files
- Progress tracking
- Summary reporting
- Pass/fail statistics

### **Individual Test Files**

#### **🧪 test_config.py**
- Environment variable validation
- Configuration loading
- CCXT format verification
- Security checks

#### **💰 test_balance.py**
- Balance fetching
- CCXT integration
- Error handling
- Alternative methods

#### **📈 test_perps_commands.py**
- Trading logic
- Symbol conversion
- Amount calculations
- Market data fetching

#### **🚪 test_exit_command.py**
- Position detection
- Exit logic
- Market order placement
- Token parsing

#### **📋 test_order_management.py**
- Order filtering
- Bulk cancellation
- Token extraction
- API integration

## 📚 Documentation

### **📚 docs/README.md**
**Documentation index and navigation**
- Quick links to all guides
- Time estimates
- Feature overview

### **📝 docs/commands.md**
**Complete command reference**
- All commands with examples
- Expected responses
- Pro tips and workflows
- Mobile optimization notes

### **🚀 docs/setup.md**
**Quick setup guide**
- 5-minute installation
- Environment configuration
- First run instructions

### **🏗️ docs/project-structure.md**
**This file - complete project organization**

### **🚀 docs/deployment.md**
**Production deployment guide**
- Server setup
- Process management
- Monitoring
- Security

## ⚙️ Configuration

### **📄 config/.env.example**
**Environment variable template**
```bash
# Hyperliquid API
HYPERLIQUID_PRIVATE_KEY=0x...
HYPERLIQUID_TESTNET=true

# Telegram Bot
TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...
TELEGRAM_ENABLED=true

# Trading Settings
DEFAULT_TRADING_SYMBOL=BTC/USDC:USDC
DEFAULT_TRADE_AMOUNT=100
LOG_LEVEL=INFO
```

## 🔄 Running the Project

### **From Source Directory**
```bash
# Main bot
python src/telegram_bot.py

# Tests
python tests/run_all_tests.py
```

### **From Project Root**
```bash
# Main bot
python -m src.telegram_bot

# Individual tests
python tests/test_config.py
```

## 📦 Dependencies

### **📄 requirements.txt**
```
ccxt>=4.2.0
python-telegram-bot>=20.0
python-dotenv>=1.0.0
requests>=2.31.0
```

### **Virtual Environment**
```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows
pip install -r requirements.txt
```

## 🔐 Security

### **Environment Variables**
- All sensitive data in `.env`
- Never commit API keys
- Use testnet for development

### **API Key Handling**
- Masked in logs
- Validation before use
- Secure storage

## 📱 Mobile Optimization

### **Telegram Interface**
- Quick action buttons
- Clean formatting
- Emoji indicators
- One-tap commands

### **Response Design**
- Mobile-friendly layout
- Concise information
- Visual hierarchy
- Touch-optimized buttons

## 🔄 Development Workflow

1. **Setup**: Follow `docs/setup.md`
2. **Test**: Run `tests/run_all_tests.py`
3. **Develop**: Edit files in `src/`
4. **Document**: Update `docs/`
5. **Test Again**: Verify all tests pass
6. **Deploy**: Follow `docs/deployment.md`

## 🎯 Key Design Principles

### **Modularity**
- Separate concerns
- Clear interfaces
- Testable components

### **Safety**
- Confirmation dialogs
- Error handling
- Testnet default

### **User Experience**
- Mobile-first design
- Clear feedback
- Professional interface

### **Maintainability**
- Comprehensive tests
- Clear documentation
- Consistent structure

**Happy coding! 🚀📱**