TCPDashboard/docs/dependency-management.md

# Dependency Management Guide

This guide explains how to manage Python dependencies in the Crypto Trading Bot Dashboard project.

## Local Development

### Adding New Dependencies

#### 1. Core Dependencies (Required for Runtime)

To add a new core dependency:

```bash
# Method 1: Add directly to pyproject.toml
# Edit pyproject.toml and add to the dependencies list:
# "new-package>=1.0.0",

# Method 2: Use UV to add and update pyproject.toml
uv add "new-package>=1.0.0"

# Sync to install
uv sync
```

#### 2. Development Dependencies (Testing, Linting, etc.)

```bash
# Add development-only dependency
uv add --dev "new-dev-package>=1.0.0"

# Or edit pyproject.toml under [project.optional-dependencies.dev]
# Then run:
uv sync --dev
```

### Installing Dependencies

```bash
# Install all dependencies
uv sync

# Install with development dependencies
uv sync --dev

# Install only production dependencies
uv sync --no-dev
```

### Updating Dependencies

```bash
# Update all dependencies to latest compatible versions
uv sync --upgrade

# Update specific package
uv sync --upgrade-package "package-name"
```

## Docker Environment

### Current Approach

The project uses a **volume-based development** approach where:
- Dependencies are installed in the local environment using UV
- Docker containers provide only infrastructure services (PostgreSQL, Redis)
- The Python application runs locally with hot reload

### Adding Dependencies for Docker-based Development

If you want to run the entire application in Docker:

#### 1. Create a Dockerfile

```dockerfile
FROM python:3.10-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    postgresql-client \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install UV
RUN pip install uv

# Copy dependency files
COPY pyproject.toml ./
COPY README.md ./

# Install dependencies
RUN uv sync --no-dev

# Copy application code
COPY . .

# Expose port
EXPOSE 8050

# Run application
CMD ["uv", "run", "python", "main.py"]
```

#### 2. Add Application Service to docker-compose.yml

```yaml
services:
  app:
    build: .
    container_name: dashboard_app
    ports:
      - "8050:8050"
    volumes:
      - .:/app
      - uv_cache:/root/.cache/uv
    environment:
      - DATABASE_URL=postgresql://dashboard:dashboard123@postgres:5432/dashboard
      - REDIS_URL=redis://redis:6379
    depends_on:
      - postgres
      - redis
    networks:
      - dashboard-network
    restart: unless-stopped

volumes:
  uv_cache:
```

#### 3. Development Workflow with Docker

```bash
# Build and start all services
docker-compose up --build

# Add new dependency
# 1. Edit pyproject.toml
# 2. Rebuild container
docker-compose build app
docker-compose up -d app

# Or use dev dependencies mount
# Mount local UV cache for faster rebuilds
```

## Hot Reload Development

### Method 1: Local Development (Recommended)

Run services in Docker, application locally with hot reload:

```bash
# Start infrastructure
python scripts/dev.py start

# Run app with hot reload
uv run python scripts/dev.py dev-server
```

### Method 2: Docker with Volume Mounts

If using Docker for the app, mount source code:

```yaml
volumes:
  - .:/app  # Mount source code
  - /app/__pycache__  # Exclude cache
```

## Best Practices

### 1. Version Pinning

```toml
# Good: Specify minimum version with compatibility
"requests>=2.31.0,<3.0.0"

# Acceptable: Major version constraint
"pandas>=2.1.0"

# Avoid: Exact pinning (except for critical deps)
"somepackage==1.2.3"  # Only if necessary
```

### 2. Dependency Categories

```toml
[project]
dependencies = [
    # Core web framework
    "dash>=2.14.0",
    
    # Database
    "sqlalchemy>=2.0.0",
    "psycopg2-binary>=2.9.0",
    
    # ... group related dependencies
]
```

### 3. Security Updates

```bash
# Check for security vulnerabilities
pip-audit

# Update specific vulnerable package
uv sync --upgrade-package "vulnerable-package"
```

## Troubleshooting

### Common Issues

1. **Dependency Conflicts**
   ```bash
   # Clear UV cache and reinstall
   uv cache clean
   uv sync --refresh
   ```

2. **PostgreSQL Connection Issues**
   ```bash
   # Ensure psycopg2-binary is installed
   uv add "psycopg2-binary>=2.9.0"
   ```

3. **Docker Build Failures**
   ```bash
   # Clean docker build cache
   docker system prune --volumes
   docker-compose build --no-cache
   ```

### Debugging Dependencies

```bash
# Show installed packages
uv pip list

# Show dependency tree
uv pip show <package-name>

# Check for conflicts
uv pip check
```

## Migration from requirements.txt

If you have an existing `requirements.txt`:

```bash
# Convert to pyproject.toml
uv add -r requirements.txt

# Or manually copy dependencies to pyproject.toml
# Then remove requirements.txt
```