GuardDen/DEV_GUIDE.md

# GuardDen Development Guide

This guide provides everything you need to start developing GuardDen locally.

## 🚀 Quick Start

```bash
# 1. Clone the repository
git clone <repository-url>
cd GuardDen

# 2. Set up development environment
./scripts/dev.sh setup

# 3. Configure environment variables
cp .env.example .env
# Edit .env with your Discord bot token and other settings

# 4. Start development environment
./scripts/dev.sh up

# 5. Run tests to verify setup
./scripts/dev.sh test
```

## 📋 Development Commands

The `./scripts/dev.sh` script provides comprehensive development automation:

### Environment Management
```bash
./scripts/dev.sh setup           # Set up development environment
./scripts/dev.sh up              # Start development containers
./scripts/dev.sh down            # Stop development containers
./scripts/dev.sh logs [service]  # Show logs (optional service filter)
./scripts/dev.sh clean           # Clean up development artifacts
```

### Code Quality
```bash
./scripts/dev.sh test            # Run tests with coverage
./scripts/dev.sh lint            # Run code quality checks
./scripts/dev.sh format          # Format code with ruff
./scripts/dev.sh security        # Run security scans
```

### Database Management
```bash
./scripts/dev.sh db migrate      # Run database migrations
./scripts/dev.sh db revision "description"  # Create new migration
./scripts/dev.sh db reset        # Reset database (destructive)
```

### Health & Monitoring
```bash
./scripts/dev.sh health check    # Run health checks
./scripts/dev.sh health json     # Health checks with JSON output
```

### Docker Operations
```bash
./scripts/dev.sh build           # Build Docker images
```

## 🐳 Development Services

When you run `./scripts/dev.sh up`, the following services are available:

| Service | URL | Purpose |
|---------|-----|---------|
| GuardDen Bot | - | Discord bot with hot reloading |
| Dashboard | http://localhost:8080 | Web interface |
| PostgreSQL | localhost:5432 | Database |
| Redis | localhost:6379 | Caching & sessions |
| PgAdmin | http://localhost:5050 | Database administration |
| Redis Commander | http://localhost:8081 | Redis administration |
| MailHog | http://localhost:8025 | Email testing |

## 🧪 Testing

### Running Tests
```bash
# Run all tests with coverage
./scripts/dev.sh test

# Run specific test files
pytest tests/test_config.py

# Run tests with verbose output
pytest -v

# Run tests in parallel (faster)
pytest -n auto
```

### Test Structure
- `tests/conftest.py` - Test fixtures and configuration
- `tests/test_*.py` - Test modules
- Test coverage reports in `htmlcov/`

### Writing Tests
- Use pytest with async support (`pytest-asyncio`)
- Comprehensive fixtures available for database, Discord mocks, etc.
- Follow naming convention: `test_*` functions in `Test*` classes

## 🔧 Code Quality

### Pre-commit Hooks
Pre-commit hooks are automatically installed during setup:
- **Ruff**: Code formatting and linting
- **MyPy**: Type checking
- **Tests**: Run tests on relevant changes

### Manual Quality Checks
```bash
# Run all quality checks
./scripts/dev.sh lint

# Format code
./scripts/dev.sh format

# Type checking only
mypy src

# Security scanning
./scripts/dev.sh security
```

### Code Style
- **Line Length**: 100 characters (configured in pyproject.toml)
- **Imports**: Sorted with ruff
- **Type Hints**: Required for all public functions
- **Docstrings**: Google style for modules and classes

## 📊 Monitoring & Debugging

### Structured Logging
```python
from guardden.utils.logging import get_logger, bind_context

logger = get_logger(__name__)

# Log with context
bind_context(user_id=123, guild_id=456)
logger.info("User performed action", action="kick", target="user#1234")
```

### Metrics Collection
```python
from guardden.utils.metrics import get_metrics

metrics = get_metrics()
metrics.record_command("ban", guild_id=123, status="success", duration=0.5)
```

### Health Checks
```bash
# Check application health
./scripts/dev.sh health check

# Get detailed JSON health report
./scripts/dev.sh health json
```

## 🗄️ Database Development

### Migrations
```bash
# Create new migration
./scripts/dev.sh db revision "add new table"

# Run migrations
./scripts/dev.sh db migrate

# Rollback one migration
./scripts/dev.sh db downgrade
```

### Database Access
- **PgAdmin**: http://localhost:5050 (admin@guardden.dev / admin)
- **Direct connection**: localhost:5432 (guardden / guardden_dev)
- **Test database**: In-memory SQLite for tests

## 🐛 Debugging

### Debug Mode
Development containers include debugging support:
- **Bot**: Debug port 5678
- **Dashboard**: Debug port 5679

### VS Code Configuration
Add to `.vscode/launch.json`:
```json
{
    "name": "Attach to Bot",
    "type": "python",
    "request": "attach",
    "host": "localhost",
    "port": 5678
}
```

### Log Analysis
```bash
# Follow all logs
./scripts/dev.sh logs

# Follow specific service logs
./scripts/dev.sh logs bot
./scripts/dev.sh logs dashboard
```

## 🔐 Security

### Environment Variables
- **Required**: `GUARDDEN_DISCORD_TOKEN`
- **Database**: `GUARDDEN_DATABASE_URL` (auto-configured for development)
- **AI**: `GUARDDEN_ANTHROPIC_API_KEY` or `GUARDDEN_OPENAI_API_KEY`

### Security Best Practices
- Never commit secrets to version control
- Use `.env` for local development secrets
- Run security scans regularly: `./scripts/dev.sh security`
- Keep dependencies updated

## 🚀 Deployment

### Building for Production
```bash
# Build optimized image
docker build -t guardden:latest .

# Build with AI dependencies
docker build --build-arg INSTALL_AI=true -t guardden:ai .
```

### CI/CD Pipeline
- **GitHub Actions**: Automated testing, security scanning, and deployment
- **Quality Gates**: 75%+ test coverage, type checking, security scans
- **Automated Deployments**: Staging (develop branch) and production (releases)

## 🆘 Troubleshooting

### Common Issues

**Port conflicts**:
```bash
# Check what's using a port
lsof -i :5432

# Use different ports in .env
POSTGRES_PORT=5433
REDIS_PORT=6380
```

**Permission errors**:
```bash
# Fix Docker permissions
sudo chown -R $USER:$USER data logs
```

**Database connection errors**:
```bash
# Reset development environment
./scripts/dev.sh down
./scripts/dev.sh clean
./scripts/dev.sh up
```

**Test failures**:
```bash
# Run tests with more verbose output
pytest -vvs

# Run specific failing test
pytest tests/test_config.py::TestSettingsValidation::test_discord_token_validation_valid -vvs
```

### Getting Help
1. Check logs: `./scripts/dev.sh logs`
2. Run health check: `./scripts/dev.sh health check`
3. Verify environment: `./scripts/dev.sh setup`
4. Check GitHub Issues for known problems

---

Happy coding! 🎉