# 📁 Project Structure

**Understanding the ManualTrader codebase organization**

## 🎯 Single Command Operation

```bash
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`)**
```python
# 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`)**
```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**
```bash
# 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**
```bash
# Single command for production
python trading_bot.py
```

## 📖 Related Documentation

- **[Setup Guide](setup.md)** - Installation and configuration
- **[Deployment Guide](deployment.md)** - Production deployment options
- **[Main README](../README.md)** - Overview and features

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