claude-code-tracker/docs/development.md

# Development Setup Guide

This guide covers setting up a local development environment for the Claude Code Project Tracker.

## Prerequisites

- **Python 3.8+** with pip
- **Git** for version control
- **Node.js 16+** (for web dashboard development)
- **SQLite3** (usually included with Python)

## Quick Setup

```bash
# Clone the repository
git clone <repository-url>
cd claude-tracker

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Initialize database
python -m app.database.init_db

# Run tests
pytest

# Start development server
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

## Project Structure

```
claude-tracker/
├── main.py                 # FastAPI application entry point
├── requirements.txt        # Production dependencies  
├── requirements-dev.txt    # Development dependencies
├── pytest.ini            # Pytest configuration
├── .env.example           # Environment variable template
├── app/                   # Main application code
│   ├── __init__.py
│   ├── models/            # Database models
│   │   ├── __init__.py
│   │   ├── base.py        # Base model class
│   │   ├── project.py     # Project model
│   │   ├── session.py     # Session model
│   │   └── ...            # Other models
│   ├── api/               # API route handlers
│   │   ├── __init__.py
│   │   ├── dependencies.py # FastAPI dependencies
│   │   ├── sessions.py    # Session endpoints
│   │   ├── conversations.py # Conversation endpoints
│   │   └── ...            # Other endpoints
│   ├── database/          # Database management
│   │   ├── __init__.py
│   │   ├── connection.py  # Database connection
│   │   ├── init_db.py     # Database initialization
│   │   └── migrations/    # Schema migrations
│   ├── analytics/         # Analytics and insights engine
│   │   ├── __init__.py
│   │   ├── productivity.py # Productivity metrics
│   │   ├── patterns.py    # Pattern analysis
│   │   └── reports.py     # Report generation
│   └── dashboard/         # Web dashboard
│       ├── static/        # CSS, JS, images
│       ├── templates/     # HTML templates
│       └── routes.py      # Dashboard routes
├── tests/                 # Test suite
│   ├── __init__.py
│   ├── conftest.py        # Pytest fixtures
│   ├── test_models.py     # Model tests
│   ├── test_api.py        # API tests
│   ├── test_analytics.py  # Analytics tests
│   └── integration/       # Integration tests
├── config/                # Configuration files
├── docs/                  # Documentation
├── data/                  # Database files (created at runtime)
└── migrations/            # Database migrations
```

## Dependencies

### Core Dependencies (`requirements.txt`)

```
fastapi==0.104.1          # Web framework
uvicorn[standard]==0.24.0 # ASGI server
sqlalchemy==2.0.23        # ORM
sqlite3                   # Database (built into Python)
pydantic==2.5.0           # Data validation
jinja2==3.1.2             # Template engine
python-multipart==0.0.6   # Form parsing
python-jose[cryptography]==3.3.0  # JWT tokens
passlib[bcrypt]==1.7.4    # Password hashing
```

### Development Dependencies (`requirements-dev.txt`)

```
pytest==7.4.3             # Testing framework
pytest-asyncio==0.21.1    # Async testing
pytest-cov==4.1.0         # Coverage reporting
httpx==0.25.2             # HTTP client for testing
faker==20.1.0             # Test data generation
black==23.11.0            # Code formatting
isort==5.12.0             # Import sorting
flake8==6.1.0             # Linting
mypy==1.7.1               # Type checking
pre-commit==3.6.0         # Git hooks
```

## Environment Configuration

Copy the example environment file:

```bash
cp .env.example .env
```

Configure these variables in `.env`:

```bash
# Database
DATABASE_URL=sqlite:///./data/tracker.db

# API Configuration  
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=true

# Security (generate with: openssl rand -hex 32)
SECRET_KEY=your-secret-key-here
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Analytics
ENABLE_ANALYTICS=true
ANALYTICS_BATCH_SIZE=1000

# Logging
LOG_LEVEL=INFO
LOG_FILE=tracker.log
```

## Database Setup

### Initialize Database

```bash
# Create database and tables
python -m app.database.init_db

# Verify database creation
sqlite3 data/tracker.db ".tables"
```

### Database Migrations

```bash
# Create a new migration
python -m app.database.migrate create "add_new_field"

# Apply migrations
python -m app.database.migrate up

# Rollback migration
python -m app.database.migrate down
```

### Sample Data

Load test data for development:

```bash
# Load sample projects and sessions
python -m app.database.seed_data

# Clear all data
python -m app.database.clear_data
```

## Testing

### Run Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=app --cov-report=html

# Run specific test file
pytest tests/test_api.py

# Run tests matching pattern
pytest -k "test_session"

# Run tests with verbose output
pytest -v
```

### Test Database

Tests use a separate in-memory database:

```python
# tests/conftest.py
@pytest.fixture
async def test_db():
    # Create in-memory SQLite database for testing
    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
    # ... setup code
```

### Writing Tests

```python
# tests/test_api.py
import pytest
from httpx import AsyncClient
from app.main import app

@pytest.mark.asyncio
async def test_create_session(test_db, test_client):
    response = await test_client.post(
        "/api/session/start",
        json={
            "session_type": "startup",
            "working_directory": "/test/path"
        }
    )
    assert response.status_code == 201
    data = response.json()
    assert data["session_id"] is not None
```

## Development Workflow

### Code Style

We use Black for formatting and isort for import sorting:

```bash
# Format code
black app/ tests/

# Sort imports  
isort app/ tests/

# Check formatting without changes
black --check app/ tests/
```

### Linting

```bash
# Run flake8 linting
flake8 app/ tests/

# Type checking with mypy
mypy app/
```

### Pre-commit Hooks

Install pre-commit hooks to run checks automatically:

```bash
# Install hooks
pre-commit install

# Run hooks manually
pre-commit run --all-files
```

### Git Workflow

1. **Create feature branch:**
   ```bash
   git checkout -b feature/new-analytics-endpoint
   ```

2. **Make changes and test:**
   ```bash
   # Make your changes
   pytest  # Run tests
   black app/ tests/  # Format code
   ```

3. **Commit changes:**
   ```bash
   git add .
   git commit -m "Add new analytics endpoint for productivity metrics"
   ```

4. **Push and create PR:**
   ```bash
   git push origin feature/new-analytics-endpoint
   ```

## API Development

### Adding New Endpoints

1. **Define Pydantic schemas** in `app/models/schemas.py`:
   ```python
   class NewFeatureRequest(BaseModel):
       name: str
       description: Optional[str] = None
   ```

2. **Create route handler** in appropriate module:
   ```python
   @router.post("/api/new-feature", response_model=NewFeatureResponse)
   async def create_new_feature(
       request: NewFeatureRequest,
       db: AsyncSession = Depends(get_db)
   ):
       # Implementation
   ```

3. **Add tests** in `tests/test_api.py`:
   ```python
   async def test_create_new_feature(test_client):
       # Test implementation
   ```

### Database Queries

Use SQLAlchemy with async/await:

```python
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import select
from app.models.project import Project

async def get_projects(db: AsyncSession, limit: int = 10):
    result = await db.execute(
        select(Project).limit(limit)
    )
    return result.scalars().all()
```

## Frontend Development

### Web Dashboard

The dashboard uses vanilla HTML/CSS/JavaScript:

```
app/dashboard/
├── static/
│   ├── css/
│   │   └── dashboard.css
│   ├── js/
│   │   ├── dashboard.js
│   │   ├── charts.js
│   │   └── api-client.js
│   └── images/
└── templates/
    ├── base.html
    ├── dashboard.html
    └── projects.html
```

### Adding New Dashboard Pages

1. **Create HTML template:**
   ```html
   <!-- app/dashboard/templates/new-page.html -->
   {% extends "base.html" %}
   {% block content %}
   <!-- Page content -->
   {% endblock %}
   ```

2. **Add route handler:**
   ```python
   @dashboard_router.get("/new-page")
   async def new_page(request: Request):
       return templates.TemplateResponse("new-page.html", {"request": request})
   ```

3. **Add JavaScript if needed:**
   ```javascript
   // app/dashboard/static/js/new-page.js
   class NewPageController {
       // Page logic
   }
   ```

## Debugging

### Logging

Configure logging in `main.py`:

```python
import logging
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    handlers=[
        logging.FileHandler("tracker.log"),
        logging.StreamHandler()
    ]
)
```

### Database Debugging

Enable SQL query logging:

```python
# In development.py
engine = create_async_engine(
    DATABASE_URL,
    echo=True  # This logs all SQL queries
)
```

### API Debugging

Use FastAPI's automatic documentation:

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

### Hook Debugging

Test hooks manually:

```bash
# Test session start
curl -X POST http://localhost:8000/api/session/start \
  -H "Content-Type: application/json" \
  -d '{"session_type":"startup","working_directory":"'$(pwd)'"}'

# Check logs
tail -f tracker.log
```

## Performance

### Database Optimization

```bash
# Analyze query performance
sqlite3 data/tracker.db "EXPLAIN QUERY PLAN SELECT ..."

# Rebuild indexes
sqlite3 data/tracker.db "REINDEX;"

# Vacuum database
sqlite3 data/tracker.db "VACUUM;"
```

### API Performance

```bash
# Profile API endpoints
pip install line_profiler
kernprof -l -v app/api/sessions.py
```

## Deployment

### Production Setup

1. **Environment variables:**
   ```bash
   DEBUG=false
   API_HOST=127.0.0.1
   ```

2. **Database backup:**
   ```bash
   cp data/tracker.db data/tracker.db.backup
   ```

3. **Run with Gunicorn:**
   ```bash
   pip install gunicorn
   gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
   ```

### Docker Setup

```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```

## Contributing

1. **Fork the repository**
2. **Create a feature branch**
3. **Add tests for new features**
4. **Ensure all tests pass**
5. **Follow code style guidelines**
6. **Submit a pull request**

### Pull Request Checklist

- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Code formatted with Black
- [ ] Type hints added
- [ ] No linting errors
- [ ] Database migrations created if needed

## Troubleshooting

### Common Issues

1. **Import errors:**
   ```bash
   # Ensure you're in the virtual environment
   source venv/bin/activate
   
   # Check Python path
   python -c "import sys; print(sys.path)"
   ```

2. **Database locked:**
   ```bash
   # Check for hanging processes
   ps aux | grep python
   
   # Remove lock files
   rm data/tracker.db-wal data/tracker.db-shm
   ```

3. **Port already in use:**
   ```bash
   # Find process using port 8000
   lsof -i :8000
   
   # Use different port
   uvicorn main:app --port 8001
   ```

### Getting Help

- Check the [API documentation](api-spec.yaml)
- Review test files for usage examples
- Open an issue for bugs or feature requests
- Join development discussions in issues