ManualTrader/PROJECT_STRUCTURE.md

📁 Project Structure

🎯 Single Command Launch

python trading_bot.py  # THIS IS ALL YOU NEED TO RUN

📂 Organized Folder Structure

trader_hyperliquid/
├── 🚀 trading_bot.py              # MAIN LAUNCHER (run this!)
├── 📊 trading_stats.json          # Your persistent statistics
├── 📝 .env                        # Your configuration (create from config/env.example)
├── 📚 requirements.txt            # Dependencies
├── 
├── 📖 Documentation/
│   ├── README.md                  # Complete guide
│   ├── SETUP_GUIDE.md            # 5-minute setup
│   ├── DEPLOYMENT_GUIDE.md       # Advanced deployment
│   └── PROJECT_STRUCTURE.md      # This file
│
├── 🔧 src/                        # Core bot modules
│   ├── __init__.py
│   ├── config.py                  # Configuration management
│   ├── hyperliquid_client.py      # Hyperliquid API wrapper
│   ├── telegram_bot.py            # Telegram interface
│   └── trading_stats.py           # Statistics engine
│
├── 🛠️ utils/                      # Utility scripts
│   ├── get_telegram_chat_id.py   # Get your Chat ID
│   ├── demo_stats.py             # See sample statistics
│   ├── simple_bot.py             # Terminal interface
│   ├── strategy_bot.py           # Automated strategies
│   └── manual_trading_bot.py     # Old manual launcher
│
├── ⚙️ config/
│   └── env.example               # Configuration template
│
├── 📋 logs/                       # Auto-created logs
│   ├── trading_bot_YYYYMMDD.log  # Daily logs
│   └── bot_errors.log            # Error log
│
└── 🐍 venv/                      # Python virtual environment

🎯 What Each File Does

🚀 Main Files (What You Use)

File	Purpose	When to Use
trading_bot.py	Main launcher	Always - This is your bot
trading_stats.json	Your trading data	Auto-created, never delete
.env	Your configuration	Create from config/env.example

📖 Documentation

File	Purpose
README.md	Complete bot documentation
SETUP_GUIDE.md	5-minute quick setup
DEPLOYMENT_GUIDE.md	Advanced deployment options
PROJECT_STRUCTURE.md	This file - folder organization

🔧 Core Modules (src/)

File	Purpose
config.py	Loads and validates your .env settings
hyperliquid_client.py	Handles all Hyperliquid API calls
telegram_bot.py	Your phone interface and trading commands
trading_stats.py	Calculates all your performance metrics

🛠️ Utilities (utils/)

File	Purpose	When to Use
get_telegram_chat_id.py	Find your Chat ID	Setup only
demo_stats.py	See sample statistics	Optional demo
simple_bot.py	Terminal interface	Testing/debugging
strategy_bot.py	Automated strategies	If you want automation

📋 Auto-Created Files

File/Folder	Purpose
logs/	All bot logs and error tracking
trading_stats.json	Your persistent trading statistics
demo_stats.json	Sample data (can delete)

🚀 How to Use This Structure

1. Initial Setup

# 1. Get your Telegram Chat ID
python utils/get_telegram_chat_id.py

# 2. Configure the bot
cp config/env.example .env
nano .env  # Add your keys and Chat ID

# 3. See what stats look like (optional)
python utils/demo_stats.py

2. Daily Usage

# Start your trading bot (ONLY command you need!)
python trading_bot.py

3. Maintenance

# Check logs
tail -f logs/trading_bot_$(date +%Y%m%d).log

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

🛡️ Built-in Safety Features

📊 Persistent Statistics

• ✅ Always saved to trading_stats.json
• ✅ Survives restarts - your data is never lost
• ✅ Automatic backups via comprehensive logging

🔄 Auto-Restart

• ✅ Up to 10 restart attempts if bot crashes
• ✅ Telegram error notifications sent to your phone
• ✅ Exponential backoff prevents spam restarts
• ✅ Graceful shutdown on Ctrl+C

📝 Comprehensive Logging

• ✅ Daily log files in logs/ folder
• ✅ Error tracking with stack traces
• ✅ Telegram notifications for errors
• ✅ Startup/shutdown notifications

⚙️ Configuration Validation

• ✅ Checks all required settings before starting
• ✅ Clear error messages with setup instructions
• ✅ Network warnings (testnet vs mainnet)
• ✅ Prevents accidental real trading

📱 Mobile-First Design

Phone Control

• 📱 All trading via Telegram commands
• 📊 Complete statistics on your phone
• 🔄 Real-time balance and P&L updates
• 📈 Professional trading metrics

Error Notifications

• 🚨 Instant error alerts to your phone
• 🔄 Restart notifications
• 🟢 Startup confirmations
• 📊 Status updates

🎯 Key Benefits of This Structure

1. 🚀 Single Command: python trading_bot.py - that's it!
2. 📊 Persistent Data: Your stats survive forever
3. 🛡️ Auto-Recovery: Bot restarts itself on errors
4. 📱 Phone Alerts: Get notified of any issues
5. 📝 Complete Logs: Full audit trail of everything
6. ⚙️ Easy Setup: Organized configuration and setup tools
7. 🔧 Modular: Clean separation of concerns

💡 Pro Tips

Keep It Simple

• Only use trading_bot.py for daily trading
• Let the bot handle all restarts and errors
• Check Telegram for status and error notifications

Backup Your Data

• Your .env file (contains your keys)
• Your trading_stats.json file (your performance data)
• Archive log files periodically

Monitor Performance

• Use /stats command in Telegram regularly
• Check daily logs for any issues
• Monitor error notifications

This structure gives you professional-grade trading infrastructure with simple phone control! 🚀📱