docs/dev/project_roles_simplification.md

Project Roles Simplification - Payment Structure Update

Date: December 11, 2024
Status: Ready for Implementation
Migration: 20251211_add_simple_compensation_fields.sql

Problem Statement

The original compensation structure was too complex for the Kenyan context where most workers are paid:

• Per day worked (e.g., 1000 KES/day)
• Per week (e.g., 7000 KES/week)
• Per work completed (e.g., 500 KES/ticket)

The old system used percentages, commissions, and bonuses which confused users during payment setup.

Solution

Add three new simple compensation types with clear cash-based fields:

New Compensation Types

1. per_day - Daily Rate

   • Field: daily_rate
   • Example: 1000 KES per day worked
   • Use case: Casual workers, helpers, daily laborers

2. per_week - Weekly Rate

   • Field: weekly_rate
   • Example: 7000 KES per week
   • Use case: Regular workers, supervisors

3. per_ticket - Per Work Done

   • Field: per_ticket_rate
   • Example: 500 KES per ticket completed
   • Use case: Technicians, field agents paid per job

Backward Compatibility

All old fields remain unchanged:

• flat_rate_amount (legacy weekly rate)
• commission_percentage
• base_amount
• bonus_percentage
• hourly_rate

Old compensation types still work:

• flat_rate
• commission
• hybrid
• hourly
• custom

Database Changes

-- New fields added
daily_rate NUMERIC(12,2)
weekly_rate NUMERIC(12,2)
per_ticket_rate NUMERIC(12,2)

-- New enum values added
'per_day'
'per_week'
'per_ticket'

Usage Examples

Example 1: Daily Worker (Helper)

{
  "role_name": "Helper",
  "compensation_type": "per_day",
  "daily_rate": 800.00,
  "description": "General helper for installations"
}

Payroll Calculation:

• Monday-Friday worked = 5 days
• Weekly pay = 5 × 800 = 4,000 KES

Example 2: Ticket-Based Technician

{
  "role_name": "Technician",
  "compensation_type": "per_ticket",
  "per_ticket_rate": 600.00,
  "description": "FTTH installation technician"
}

Payroll Calculation:

• Completed 8 tickets this week
• Weekly pay = 8 × 600 = 4,800 KES

Example 3: Weekly Supervisor

{
  "role_name": "Supervisor",
  "compensation_type": "per_week",
  "weekly_rate": 7000.00,
  "description": "Site supervisor"
}

Payroll Calculation:

• Fixed weekly pay = 7,000 KES

Migration Steps

1. Run SQL Migration

   # In Supabase SQL Editor
   # Execute: supabase/migrations/20251211_add_simple_compensation_fields.sql
   

2. Update Python Code (Already done)

   • ✅ Models updated (src/app/models/project.py)
   • ✅ Enums updated (src/app/models/enums.py)
   • ✅ Schemas updated (src/app/schemas/project.py)

3. Update Frontend (TODO)

   • Show simple types first (per_day, per_week, per_ticket)
   • Move complex types to "Advanced" section
   • Add clear labels in Swahili/English

4. Update Payroll Service (TODO)

   • Add calculation logic for new types
   • Handle daily_rate: days_worked × daily_rate
   • Handle weekly_rate: fixed amount
   • Handle per_ticket_rate: tickets_closed × per_ticket_rate

Payroll Service Updates Needed

# In user_payroll calculation
if role.compensation_type == "per_day":
    earnings = days_worked * role.daily_rate
elif role.compensation_type == "per_week":
    earnings = role.weekly_rate
elif role.compensation_type == "per_ticket":
    earnings = tickets_closed * role.per_ticket_rate
# ... existing logic for old types

Benefits

1. Clarity: "1000 KES per day" is immediately clear
2. Simplicity: No percentages or complex calculations
3. Kenyan Context: Matches how people actually get paid
4. Backward Compatible: Existing roles continue working
5. Flexible: Can still use advanced types when needed

Next Steps

1. ✅ Create migration file
2. ✅ Update Python models/schemas
3. ⏳ Run migration in Supabase
4. ⏳ Update payroll calculation service
5. ⏳ Update frontend UI
6. ⏳ Test with real data
7. ⏳ Update documentation

Notes

• No min/max limits added (keeping it simple)
• No per_hour type added (hourly already exists)
• All changes are additive (no deletions)
• Zero breaking changes to existing code