ManualTrader/docs/project-structure.md

🏗️ 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

# 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

# Main bot
python src/telegram_bot.py

# Tests
python tests/run_all_tests.py

From Project Root

# 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

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! 🚀📱