TimeTrack/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

TimeTrack is a comprehensive web-based time tracking application built with Flask that provides enterprise-level time management capabilities for teams and organizations. It features multi-tenancy, role-based access control, project/team management, billing/invoicing, and secure authentication with 2FA.

Tech Stack

• Backend: Flask 2.0.1 with SQLAlchemy ORM
• Database: PostgreSQL (production) / SQLite (development)
• Migrations: Flask-Migrate (Alembic-based)
• Frontend: Server-side rendered Jinja2 templates with vanilla JavaScript
• Authentication: Session-based with TOTP 2FA support and password reset via email
• Export: Pandas for CSV/Excel, ReportLab for PDF generation
• Mobile: Progressive Web App (PWA) support with optimized mobile UI

Development Setup

Local Development

# Using virtual environment
source .venv/bin/activate  # or pipenv shell

# Set environment variables (PostgreSQL example)
export DATABASE_URL="postgresql://timetrack:timetrack123@localhost:5432/timetrack"

# Run the application
python app.py

Docker Development

# Standard docker-compose (uses PostgreSQL)
docker-compose up

# Debug mode with hot-reload
docker-compose -f docker-compose.debug.yml up

Database Operations

Flask-Migrate Commands

# Create a new migration
python create_migration.py "Description of changes"

# Apply pending migrations
python apply_migration.py

# Check current migration state
python check_migration_state.py

# Clean migration state (CAUTION: destructive)
python clean_migration_state.py

# For Docker environments
docker exec timetrack-timetrack-1 python create_migration.py "Description"
docker exec timetrack-timetrack-1 python apply_migration.py

Standard Flask-Migrate Commands

# Create migration
flask db migrate -m "Description"

# Apply migrations
flask db upgrade

# Rollback one revision
flask db downgrade

# Show current revision
flask db current

# Show migration history
flask db history

Key Architecture Patterns

1. Blueprint-Based Modular Architecture

Routes are organized into blueprints by feature domain:

• /routes/auth.py - Authentication and authorization decorators
• /routes/projects.py - Project management
• /routes/invoice.py - Billing and invoicing
• /routes/tax_configuration.py - Tax management
• /routes/teams.py - Team management
• /routes/export.py - Data export functionality

2. Model Organization

Models are split by domain in /models/:

• user.py - User, Role, UserPreferences
• company.py - Company, CompanySettings, CompanyWorkConfig
• project.py - Project, ProjectCategory
• team.py - Team
• time_entry.py - TimeEntry
• invoice.py - Invoice, InvoiceLineItem, InvoiceStatus
• tax_configuration.py - TaxConfiguration
• enums.py - BillingType, AccountType, etc.

3. Multi-Tenancy Pattern

All data is scoped by company_id with automatic filtering:

# Common pattern in routes
projects = Project.query.filter_by(company_id=g.user.company_id).all()

4. Role-Based Access Control

Decorators enforce permissions:

@role_required(Role.SUPERVISOR)  # Supervisor and above
@admin_required  # Admin and System Admin only
@company_required  # Ensures user has company context

5. Billing Architecture

• Projects support multiple billing types: NON_BILLABLE, HOURLY, DAILY_RATE, FIXED_RATE
• Invoices support net/gross pricing with country-specific tax configurations
• TimeEntry calculates billing based on project settings (8-hour day for daily rates)

Common Development Tasks

Adding a New Feature

1. Create model in appropriate file under /models/
2. Create blueprint in /routes/ with proper decorators
3. Register blueprint in app.py
4. Create templates in /templates/
5. Run migration: python create_migration.py "Add feature X"

Testing Database Changes

# Check what will be migrated
python check_migration_state.py

# Test in isolated environment
docker-compose -f docker-compose.debug.yml up

# Apply to development database
DATABASE_URL="postgresql://..." python apply_migration.py

Working with Billing Features

When modifying billing/invoice features:

1. Check models/enums.py for BillingType values
2. Update TimeEntry.calculate_billing_amount() for new billing logic
3. Update Invoice.calculate_totals() for tax calculations
4. Ensure templates handle all billing types (hourly/daily rate display)

Important Implementation Details

Session Management

• Sessions are permanent with 7-day lifetime
• User context loaded in app.before_request() via g.user
• Company context available via g.company

Time Calculations

• Time entries use UTC internally, converted for display
• Rounding rules configured per company/user
• Break time calculations handled in TimeEntry model

Export System

• Pandas handles CSV/Excel generation
• ReportLab for PDF invoices
• Export routes handle large datasets with streaming

Email Configuration

• Flask-Mail configured via environment variables
• MAIL_SERVER, MAIL_PORT, MAIL_USERNAME required
• Used for user invitations and password resets

Authentication Features

• Password reset functionality with secure tokens (1-hour expiry)
• Two-factor authentication (2FA) using TOTP
• Session-based authentication with "Remember Me" option
• Email verification for new accounts (configurable)

Mobile UI Features

• Progressive Web App (PWA) manifest for installability
• Mobile-optimized navigation with hamburger menu and bottom nav
• Touch-friendly form inputs and buttons (44px minimum touch targets)
• Responsive tables with card view on small screens
• Pull-to-refresh functionality
• Mobile gestures support (swipe, pinch-to-zoom)
• Date/time pickers that respect user preferences

Environment Variables

Required for production:

• DATABASE_URL - PostgreSQL connection string
• SECRET_KEY - Flask session secret
• MAIL_SERVER, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD - Email config

Optional:

• FLASK_ENV - Set to 'development' for debug mode
• FORCE_HTTPS - Set to 'true' for HTTPS enforcement
• TRUST_PROXY_HEADERS - Set to 'true' when behind reverse proxy

Troubleshooting

Migration Issues

1. Run python check_migration_state.py to verify database state
2. Check /migrations/versions/ for migration files
3. If stuck, use clean_migration_state.py (careful - destructive)

Import Errors

• Ensure all model imports in routes use: from models import ModelName
• Blueprint registration order matters in app.py

Database Connection

• PostgreSQL requires running container or local instance
• Default fallback to SQLite at /data/timetrack.db
• Check docker-compose.yml for PostgreSQL credentials