ManualTrader/docs/project-structure.md

📁 Project Structure

Understanding the ManualTrader codebase organization

🎯 Single Command Operation

python trading_bot.py  # Only command you need to run

📂 Directory Structure

ManualTrader/
├── 🚀 trading_bot.py              # MAIN LAUNCHER
├── 📊 trading_stats.json          # Persistent trading data
├── 📝 .env                        # Your configuration
├── 📄 requirements.txt            # Python dependencies
├── 📄 .gitignore                  # Git ignore rules
│
├── 🔧 src/                        # Core application modules
│   ├── __init__.py
│   ├── config.py                  # Configuration management
│   ├── hyperliquid_client.py      # CCXT-style API wrapper
│   ├── telegram_bot.py            # Telegram interface
│   └── trading_stats.py           # Statistics engine
│
├── 🛠️ utils/                      # Utilities and helpers
│   ├── get_telegram_chat_id.py   # Chat ID finder (main)
│   ├── simple_chat_id.py         # Alternative for servers
│   ├── demo_stats.py             # Statistics demonstration
│   ├── simple_bot.py             # Terminal interface
│   ├── strategy_bot.py           # Automated strategies
│   └── manual_trading_bot.py     # Legacy launcher
│
├── ⚙️ config/                     # Configuration templates
│   └── env.example               # Environment template
│
├── 📋 logs/                       # Auto-created logging
│   ├── trading_bot_YYYYMMDD.log  # Daily bot logs
│   └── bot_errors.log            # Error log
│
├── 📖 docs/                       # Documentation
│   ├── setup.md                  # Setup instructions
│   ├── project-structure.md      # This file
│   └── deployment.md             # Deployment guide
│
└── 🐍 venv/                      # Python virtual environment

🎯 Core Files

Main Launcher

• trading_bot.py - The only file you run
  • Auto-restart capability
  • Error handling and notifications
  • Configuration validation
  • Comprehensive logging

Core Modules (src/)

• config.py - CCXT-style configuration management
• hyperliquid_client.py - Enhanced API wrapper with error handling
• telegram_bot.py - Mobile-optimized trading interface
• trading_stats.py - Professional analytics engine

Data Files

• trading_stats.json - Your persistent trading statistics
• .env - Your sensitive configuration (not in git)

🛠️ Utility Scripts

Script	Purpose	When to Use
get_telegram_chat_id.py	Find your Telegram Chat ID	Setup only
simple_chat_id.py	Alternative Chat ID finder	If main script fails
demo_stats.py	Show sample statistics	See what bot tracks
simple_bot.py	Terminal interface	Quick testing
strategy_bot.py	Automated trading	If you want automation

📊 Data Flow

1. trading_bot.py (launcher)
   ↓
2. src/config.py (load configuration)
   ↓
3. src/hyperliquid_client.py (connect to exchange)
   ↓
4. src/telegram_bot.py (start interface)
   ↓
5. src/trading_stats.py (track performance)
   ↓
6. trading_stats.json (persist data)

🔧 Module Details

Config Management (src/config.py)

# CCXT-style configuration
config = {
    'apiKey': 'your_private_key',
    'secret': 'your_secret_key',
    'testnet': True,
    'sandbox': True
}

API Client (src/hyperliquid_client.py)

• CCXT-compatible initialization
• Enhanced error handling
• Connection testing
• Safe parameter logging

Telegram Interface (src/telegram_bot.py)

• Mobile-optimized UI
• Inline keyboards
• Order confirmations
• Real-time notifications

Statistics Engine (src/trading_stats.py)

• FIFO P&L calculation
• Professional risk metrics
• Persistent data storage
• Performance analytics

🛡️ Security Features

Sensitive Data Protection

• .env files excluded from git
• API keys masked in logs
• Trading data locally stored

Error Recovery

• Auto-restart on crashes
• Comprehensive error logging
• Telegram error notifications

📝 Configuration Files

Environment Variables (.env)

# Authentication
HYPERLIQUID_PRIVATE_KEY=your_private_key_here
HYPERLIQUID_SECRET_KEY=your_secret_key_here

# Network
HYPERLIQUID_TESTNET=true

# Telegram
TELEGRAM_BOT_TOKEN=your_token_here
TELEGRAM_CHAT_ID=your_chat_id_here
TELEGRAM_ENABLED=true

Dependencies (requirements.txt)

• hyperliquid==0.4.66 - Exchange library
• python-telegram-bot[webhooks]==20.7 - Telegram interface
• python-dotenv==1.1.0 - Environment management
• pandas==2.2.3 - Data analysis
• numpy==2.2.6 - Numerical computing

🔄 Development Workflow

Testing Changes

# Test configuration
python -c "import sys; sys.path.insert(0, 'src'); from config import Config; Config.validate()"

# Test terminal interface
python utils/simple_bot.py

# Test statistics
python utils/demo_stats.py

Production Deployment

# Single command for production
python trading_bot.py

📖 Related Documentation

• Setup Guide - Installation and configuration
• Deployment Guide - Production deployment options
• Main README - Overview and features

This architecture provides professional-grade reliability with simple operation! 🚀