# 📁 Project Structure

## 🎯 **Single Command Launch**
```bash
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**
```bash
# 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**
```bash
# Start your trading bot (ONLY command you need!)
python trading_bot.py
```

### **3. Maintenance**
```bash
# 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! 🚀📱**