TimeTrack/MIGRATION_FREELANCERS.md

Freelancer Migration Guide

This document explains the database migration for freelancer support in TimeTrack.

Overview

The freelancer migration adds support for independent users who can register without a company token. It introduces:

1. Account Types: Users can be either "Company User" or "Freelancer"
2. Personal Companies: Freelancers automatically get their own company workspace
3. Business Names: Optional field for freelancers to specify their business name

Database Changes

User Table Changes

• account_type VARCHAR(20) DEFAULT 'COMPANY_USER' - Type of account
• business_name VARCHAR(100) - Optional business name for freelancers
• company_id INTEGER - Foreign key to company table (for multi-tenancy)

Company Table Changes

• is_personal BOOLEAN DEFAULT 0 - Marks companies auto-created for freelancers

Migration Options

Option 1: Automatic Migration (Recommended)

The main migration script (migrate_db.py) now includes freelancer support:

python migrate_db.py

This will:

• Add new columns to existing tables
• Create company table if it doesn't exist
• Set default values for existing users

Option 2: Dedicated Freelancer Migration

Use the dedicated freelancer migration script:

python migrate_freelancers.py

Option 3: Manual SQL Migration

If you prefer manual control:

-- Add columns to user table
ALTER TABLE user ADD COLUMN account_type VARCHAR(20) DEFAULT 'COMPANY_USER';
ALTER TABLE user ADD COLUMN business_name VARCHAR(100);
ALTER TABLE user ADD COLUMN company_id INTEGER;

-- Create company table (if it doesn't exist)
CREATE TABLE company (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(100) UNIQUE NOT NULL,
    slug VARCHAR(50) UNIQUE NOT NULL,
    description TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_personal BOOLEAN DEFAULT 0,
    is_active BOOLEAN DEFAULT 1,
    max_users INTEGER DEFAULT 100
);

-- Or add column to existing company table
ALTER TABLE company ADD COLUMN is_personal BOOLEAN DEFAULT 0;

-- Update existing users
UPDATE user SET account_type = 'COMPANY_USER' WHERE account_type IS NULL;

Post-Migration Steps

For Existing Installations

1. Create Default Company: If you have existing users without a company, create one:

   # In Python/Flask shell
   from models import db, Company, User
   
   # Create default company
   company = Company(
       name="Default Company", 
       slug="default-company",
       description="Default company for existing users"
   )
   db.session.add(company)
   db.session.flush()
   
   # Assign existing users to default company
   User.query.filter_by(company_id=None).update({'company_id': company.id})
   db.session.commit()
   

2. Verify Migration: Check that all users have a company_id:

   SELECT COUNT(*) FROM user WHERE company_id IS NULL;
   -- Should return 0
   

Testing Freelancer Registration

1. Visit /register/freelancer
2. Register a new freelancer account
3. Verify the personal company was created
4. Test login and time tracking functionality

New Features Available

Freelancer Registration

• URL: /register/freelancer
• Features:
  • No company token required
  • Auto-creates personal workspace
  • Optional business name field
  • Immediate account activation

Registration Options

• Company Registration: /register (existing)
• Freelancer Registration: /register/freelancer (new)
• Login Page: Shows both registration options

User Experience

• Freelancers get admin privileges in their personal company
• Can create projects and track time immediately
• Personal workspace is limited to 1 user by default
• Can optionally expand to hire employees later

Troubleshooting

Common Issues

Migration fails with "column already exists"

• This is normal if you've run the migration before
• The migration script checks for existing columns

Users missing company_id after migration

• Run the post-migration steps above to assign a default company

Freelancer registration fails

• Check that the AccountType enum is imported correctly
• Verify database migration completed successfully

Rollback (Limited)

SQLite doesn't support dropping columns, so rollback is limited:

python migrate_freelancers.py rollback

For full rollback, you would need to:

1. Export user data
2. Recreate tables without freelancer columns
3. Re-import data

Verification Commands

# Verify migration applied
python migrate_freelancers.py verify

# Check table structure
sqlite3 timetrack.db ".schema user"
sqlite3 timetrack.db ".schema company"

# Check data
sqlite3 timetrack.db "SELECT account_type, COUNT(*) FROM user GROUP BY account_type;"

Security Considerations

• Freelancers get unique usernames/emails globally (not per-company)
• Personal companies are limited to 1 user by default
• Freelancers have admin privileges only in their personal workspace
• Multi-tenant isolation is maintained

Future Enhancements

• Allow freelancers to upgrade to team accounts
• Billing integration for freelancer vs company accounts
• Advanced freelancer-specific features
• Integration with invoicing systems