Crew Builder Module Flow¶

Overview¶

The crew builder module implements a three-tier architecture for managing crew compositions, location-specific labor rates, and project-contextualized service crew assignments. This system enables flexible rate management across different locations, time periods, and project types.

Three-Tier Architecture¶

1. Crew Trades (Universal Trade Definitions)¶

Purpose: Define universal trade codes and standardized labor designations across all locations
Container: CrewTrades (Partition key: /tradeCode)
Endpoints: /api/v1/crews/trades
Key Fields:
tradeCode: Unique identifier (e.g., "ELEC", "CARP", "PLMB")
tradeName: Display name (e.g., "Electrician", "Carpenter")
category: Trade category (e.g., "skilled", "unskilled", "professional")
description: Trade description
Examples:
Trade Code: ELEC, Trade Name: Electrician, Category: skilled
Trade Code: CARP, Trade Name: Carpenter, Category: skilled
Trade Code: PLMB, Trade Name: Plumber, Category: skilled

2. Crew Members (Location/Time-Specific Rate Cards)¶

Purpose: Store location, time, and project-specific labor rates for each trade designation
Container: CrewMembers (Partition key: /locationKey - composite key)
Location Key Format: country|province|tradeCode|laborDesignation
Endpoints: /api/v1/crews/members
Key Attributes:
Trade reference: tradeCode, laborDesignation (e.g., "Journeyman", "Foreman", "Apprentice")
Location: country, province, region (e.g., "Canada", "Ontario", "Toronto")
Time context: year, quarter (e.g., 2025, "Q1")
Project context: projectType (e.g., "commercial", "residential", "industrial")
Rates:
- baseRate: Standard hourly rate
- overtimeRate: 1.5x rate (typically)
- doubleTimeRate: 2.0x rate
- tripleTimeRate: 3.0x rate
Examples:
Canada|Ontario|ELEC|Journeyman for Q1 2025, Commercial: $45/hr base, $67.50/hr OT
Canada|Quebec|ELEC|Journeyman for Q1 2025, Commercial: $42/hr base, $63/hr OT
SaudiArabia|Asir|ELEC|Journeyman for Q1 2025, Commercial: $25/hr base, $37.50/hr OT

3. Crews (Reusable Crew Templates)¶

Purpose: Define reusable crew templates with manpower and equipment composition
Container: Crews (Partition key: /crewId)
Endpoints: /api/v1/crews
Key Attributes:
Identification: crewCode, crewName
discipline: Crew discipline (e.g., "electrical", "concrete", "mechanical")

manpower: Array of trade composition with quantities

[
  {"tradeCode": "ELEC", "laborDesignation": "Foreman", "quantity": 1},
  {"tradeCode": "ELEC", "laborDesignation": "Journeyman", "quantity": 4},
  {"tradeCode": "ELEC", "laborDesignation": "Apprentice", "quantity": 2}
]

equipment: Array of equipment with quantities

[
  {"equipmentCode": "TOOL-001", "quantity": 1},
  {"equipmentCode": "VAN-001", "quantity": 1}
]

productivityFactor: Multiplier for productivity adjustments (default: 1.0)
Example:
"Electrical Installation Crew" (ELEC-001)
- 1x ELEC/Foreman
- 4x ELEC/Journeyman
- 2x ELEC/Apprentice
- 1x Tool Set
- 1x Service Van

Project Contextualization Flow¶

Step 1: Create Project¶

Define project with location attributes:
Country, Province, Region
Year, Quarter
Project Type
Contract Type

Step 2: Import Crew to Project¶

Select a universal crew template
System matches crew-trades to crew-members based on:
Project location (country, province, region)
Time context (year, quarter)
Project type
Endpoint: POST /projects/{projectId}/import-crew

Step 3: Contextualized Crew¶

System returns crew with location-specific rates
For each crew-trade in the composition:
Find matching crew-member rate card
Apply base rate and overtime multipliers
Handle unmatched trades with warnings

Step 4: Apply Indirect Costs¶

Calculate crew rates with project indirect costs
Apply percentage-based markups to base rates
Generate final crew hourly rates
Endpoint: POST /projects/{projectId}/crew-rates

Rate Calculation Example¶

Universal Crew: "Concrete Pour Crew"
1x CONC/Foreman
3x CONC/Finisher
2x LABR/Helper
Project Context:
Location: Canada/Ontario/Toronto
Year: 2025, Quarter: Q1
Project Type: Commercial
Matched Rates:
CONC/Foreman: $35/hr base, $52.50/hr OT
CONC/Finisher: $27/hr base, $40.50/hr OT
LABR/Helper: $20/hr base, $30/hr OT
With Indirect Costs (e.g., 45% total):
CONC/Foreman: $50.75/hr crew rate
CONC/Finisher: $39.15/hr crew rate
LABR/Helper: $29/hr crew rate
Total Crew Rate: Sum of all contextualized rates × quantities

Integration with Services and MTO¶

Service Crews (Project-Specific Crew Assignments)¶

Container: ServiceCrews (Partition key: /serviceCrewId)
Endpoints: /api/v1/service-crews
Purpose: Link crew templates to specific services with project context and indirect costs
Key Fields:
serviceId: Links to estimation service
crewId: References crew template
crewCode, crewName: Denormalized for quick access
quantity: Number of crew instances needed
rate: Calculated hourly crew rate (from project location + crew members)
total: Total cost (rate × quantity × hours)

indirectCosts: Project-specific indirect cost breakdown

{
  "labour": {
    "employerHealthTax": 5.0,
    "employmentInsurance": 3.5,
    "canadaPensionPlan": 6.0,
    "workersCompensation": 8.0,
    "vacationPay": 4.0,
    "statutoryHolidays": 3.0,
    "totalPercentage": 29.5
  },
  "equipment": {
    "smallTools": 2.0,
    "consumables": 1.5,
    "maintenance": 3.0,
    "totalPercentage": 6.5
  }
}

Material Takeoff (MTO) Integration¶

Container: MaterialTakeoff (Partition key: /projectId)
Endpoints: /api/v1/mto
Purpose: Discipline-based material quantity tracking for estimation
Integration: Works alongside service crews to provide complete project estimates
Key Fields:
projectId, serviceId: Links to project and service
discipline: Discipline category (electrical, mechanical, concrete, etc.)
items[]: Array of material items with quantities, units, and costs
totalMaterialCost: Sum of all material costs for the discipline

API Endpoints Summary¶

Universal Reference Data (CRUD)¶

GET/POST /api/v1/crews/trades - Manage universal trade definitions
GET/POST /api/v1/crews/trades/{tradeId} - Individual trade operations
GET/POST /api/v1/crews/members - Manage location/time-specific rate cards
GET/POST /api/v1/crews/members/{memberId} - Individual crew member operations
GET/POST /api/v1/crews - Manage reusable crew templates
GET/PUT/DELETE /api/v1/crews/{crewId} - Individual crew operations
POST /api/v1/crews/{crewId}/duplicate - Duplicate crew template

Project-Specific Operations¶

GET/POST /api/v1/service-crews - Service crew assignments
GET/PUT/DELETE /api/v1/service-crews/{serviceCrewId} - Individual service crew operations
POST /api/v1/service-crews/bulk - Bulk create service crews for a service
GET/POST /api/v1/mto - Material takeoff operations
GET/PUT/DELETE /api/v1/mto/{mtoId} - Individual MTO operations

Supporting Endpoints¶

GET /api/v1/equipment - Equipment catalog
POST /api/v1/equipment - Create equipment
GET/PUT/DELETE /api/v1/equipment/{equipmentId} - Equipment operations

Key Benefits¶

Reusability: Universal crew templates can be used across multiple projects and services
Location Intelligence: Automatic rate matching based on project location (country/province)
Time Context: Rate cards versioned by year and quarter for historical accuracy
Project Type Flexibility: Different rates for commercial, residential, industrial projects
Indirect Cost Management: Project-specific indirect costs stored with service crews
Rate Calculation Transparency: Frontend calculates blended rates, backend stores final values
MTO Integration: Complete project estimation with labor (crews) and materials (MTO)
Audit Trail: All rates and costs tracked with timestamps and user information