Initial commit: Claude Code Project Tracker

Add comprehensive development intelligence system that tracks: - Development sessions with automatic start/stop - Full conversation history with semantic search - Tool usage and file operation analytics - Think time and engagement analysis - Git activity correlation - Learning pattern recognition - Productivity insights and metrics Features: - FastAPI backend with SQLite database - Modern web dashboard with interactive charts - Claude Code hook integration for automatic tracking - Comprehensive test suite with 100+ tests - Complete API documentation (OpenAPI/Swagger) - Privacy-first design with local data storage 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-11 02:59:21 -06:00 · 2025-08-11 02:59:21 -06:00 · 44ed9936b7
commit 44ed9936b7
48 changed files with 9707 additions and 0 deletions
--- a/docs/development.md
+++ b/docs/development.md
@ -0,0 +1,562 @@
+# 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