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

# 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:

cp .env.example .env

Configure these variables in .env:

# 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

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

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

Database Migrations

# 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:

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

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

Testing

Run Tests

# 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:

# 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

# 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:

# Format code
black app/ tests/

# Sort imports  
isort app/ tests/

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

Linting

# Run flake8 linting
flake8 app/ tests/

# Type checking with mypy
mypy app/

Pre-commit Hooks

Install pre-commit hooks to run checks automatically:

# Install hooks
pre-commit install

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

Git Workflow

1. Create feature branch:

   git checkout -b feature/new-analytics-endpoint
   

2. Make changes and test:

   # Make your changes
   pytest  # Run tests
   black app/ tests/  # Format code
   

3. Commit changes:

   git add .
   git commit -m "Add new analytics endpoint for productivity metrics"
   

4. Push and create PR:

   git push origin feature/new-analytics-endpoint
   

API Development

Adding New Endpoints

1. Define Pydantic schemas in app/models/schemas.py:

   class NewFeatureRequest(BaseModel):
       name: str
       description: Optional[str] = None
   

2. Create route handler in appropriate module:

   @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:

   async def test_create_new_feature(test_client):
       # Test implementation
   

Database Queries

Use SQLAlchemy with async/await:

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:

   <!-- app/dashboard/templates/new-page.html -->
   {% extends "base.html" %}
   {% block content %}
   <!-- Page content -->
   {% endblock %}
   

2. Add route handler:

   @dashboard_router.get("/new-page")
   async def new_page(request: Request):
       return templates.TemplateResponse("new-page.html", {"request": request})
   

3. Add JavaScript if needed:

   // app/dashboard/static/js/new-page.js
   class NewPageController {
       // Page logic
   }
   

Debugging

Logging

Configure logging in main.py:

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:

# 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:

# 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

# 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

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

Deployment

Production Setup

1. Environment variables:

   DEBUG=false
   API_HOST=127.0.0.1
   

2. Database backup:

   cp data/tracker.db data/tracker.db.backup
   

3. Run with Gunicorn:

   pip install gunicorn
   gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
   

Docker Setup

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:

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

2. Database locked:

   # 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:

   # Find process using port 8000
   lsof -i :8000
   
   # Use different port
   uvicorn main:app --port 8001
   

Getting Help

• Check the API documentation
• Review test files for usage examples
• Open an issue for bugs or feature requests
• Join development discussions in issues