Skip to main content

Job Management

This document covers the job management system architecture and implementation details for the AttuneLogic API.

🏗️ Job Architecture​

Core Job Model​

The job management system is built around a flexible, multi-industry job model that supports:

  • Trucking Industry: Load management, route optimization, delivery tracking
  • Service/Repair Industry: Work orders, maintenance schedules, service requests
  • Universal Features: Scheduling, status tracking, resource allocation

Job Lifecycle​

Created → Scheduled → Assigned → In Progress → Completed → Invoiced → Archived

📊 Job States and Transitions​

Primary States​

  • pending: Job created but not yet scheduled
  • scheduled: Job scheduled with date/time assignment
  • assigned: Job assigned to specific resources (drivers, technicians)
  • in_progress: Job actively being worked on
  • completed: Job finished successfully
  • cancelled: Job cancelled before completion
  • failed: Job could not be completed

Industry-Specific Sub-States​

Trucking Industry​

  • dispatched: Load assigned to driver
  • en_route_pickup: Driver heading to pickup location
  • at_pickup: Driver at pickup location
  • loaded: Cargo loaded, en route to delivery
  • at_delivery: Driver at delivery location
  • delivered: Cargo delivered successfully

Note: Trucking has a canonical, snake_case Job + Leg status system with backward-compatible normalization. See: docs/developer/development/trucking-status-canonicalization.md

Service/Repair Industry​

  • diagnosed: Issue identified and assessed
  • parts_ordered: Required parts ordered
  • parts_received: Parts available for repair
  • repair_in_progress: Active repair work
  • testing: Post-repair testing and validation
  • customer_approval: Awaiting customer approval

🗄️ Database Schema​

Jobs Collection​

{
  _id: ObjectId,
  title: String,
  description: String,
  status: String,
  priority: String, // low, medium, high, urgent
  appType: String, // trucking, serviceRepair, hvac, plumbing, electrical

  // Scheduling
  scheduledDate: Date,
  estimatedDuration: Number, // minutes
  actualStartTime: Date,
  actualEndTime: Date,

  // Assignment
  assignedTo: [ObjectId], // references to Users
  assignedTeam: ObjectId, // reference to Team

  // Location
  serviceAddress: Object,
  pickupAddress: Object, // trucking specific
  deliveryAddress: Object, // trucking specific

  // Industry-Specific Data
  industryData: {
    // Trucking
    loadDetails: Object,
    routeOptimization: Object,
    driverRequirements: Object,

    // Service/Repair
    equipmentDetails: Object,
    serviceType: String,
    partsRequired: Array,
    customerPreferences: Object
  },

  // Relationships
  parentCompany: ObjectId,
  client: ObjectId,
  equipment: [ObjectId],
  items: [ObjectId], // job items/sub-tasks

  // Metadata
  createdAt: Date,
  updatedAt: Date,
  createdBy: ObjectId,
  updatedBy: ObjectId,

  // Tracking
  timeline: [Object], // status change history
  notes: [Object], // comments and updates
  attachments: [Object] // photos, documents
}

🔄 Job Item System​

Job Items (Sub-Tasks)​

Jobs can contain multiple items representing:

  • Trucking: Multiple stops, cargo types, delivery requirements
  • Service/Repair: Individual repair tasks, parts installation, testing procedures

Item Schema​

{
  _id: ObjectId,
  jobId: ObjectId,
  title: String,
  description: String,
  status: String,
  sequence: Number, // order of execution

  // Time tracking
  estimatedTime: Number,
  actualTime: Number,
  startTime: Date,
  endTime: Date,

  // Resources
  assignedTo: ObjectId,
  requiredSkills: [String],
  toolsRequired: [String],
  partsRequired: [Object],

  // Completion
  completionNotes: String,
  qualityCheck: Boolean,
  customerSignature: String,
  photos: [String],

  // Industry-specific
  industryData: Object
}

🚀 API Endpoints​

Core Job Operations​

// Create job
POST /api/v1/jobs
Body: CreateJobRequest

// Get jobs (with filtering)
GET /api/v1/jobs?status=pending&appType=trucking&assignedTo=userId

// Get single job
GET /api/v1/jobs/:jobId

// Update job
PATCH /api/v1/jobs/:jobId
Body: UpdateJobRequest

// Delete job
DELETE /api/v1/jobs/:jobId

// Job status transitions
POST /api/v1/jobs/:jobId/status
Body: { status: 'in_progress', notes: 'Started work' }

Job Item Operations​

// Add item to job
POST /api/v1/jobs/:jobId/items
Body: CreateJobItemRequest

// Update job item
PATCH /api/v1/jobs/:jobId/items/:itemId

// Complete job item
POST /api/v1/jobs/:jobId/items/:itemId/complete
Body: CompletionData

// Reorder job items
POST /api/v1/jobs/:jobId/items/reorder
Body: { itemIds: [id1, id2, id3] }

🏭 Industry-Specific Features​

Trucking Industry​

  • Route Optimization: Integration with mapping services
  • Load Optimization: Weight, space, and compatibility calculations
  • Driver Assignment: Based on qualifications, location, HOS compliance
  • Real-time Tracking: GPS integration for live location updates
  • BOL Management: Digital bill of lading generation and tracking

Service/Repair Industry​

  • Skill-Based Assignment: Match technicians to required skills
  • Parts Management: Inventory tracking and automatic ordering
  • Customer Communication: Automated updates and approval workflows
  • Equipment History: Service history and maintenance schedules
  • Quality Assurance: Photo documentation and completion checklists

📱 Mobile Integration​

Mobile Job Features​

  • Offline Capability: Work without internet connection
  • Photo Capture: Document progress and completion
  • Digital Signatures: Customer approval and sign-off
  • Real-time Updates: Sync status changes immediately
  • Navigation: Integrated GPS for route guidance

Mobile API Endpoints​

// Sync jobs for mobile user
GET /api/v1/mobile/jobs/sync?lastSync=timestamp

// Update job status from mobile
POST /api/v1/mobile/jobs/:jobId/status
Body: { status, location, timestamp, photos }

// Upload job completion data
POST /api/v1/mobile/jobs/:jobId/complete
Body: CompletionData with photos and signatures

🔍 Search and Filtering​

// Search with multiple criteria
GET /api/v1/jobs/search?q=urgent+repair&dateRange=2024-01-01,2024-01-31&status=pending,assigned&assignedTo=userId

// Geospatial search
GET /api/v1/jobs/nearby?lat=40.7128&lng=-74.0060&radius=50&unit=miles

// Industry-specific filters
GET /api/v1/jobs?appType=trucking&loadType=flatbed&route=interstate

📊 Performance Optimization​

Database Indexes​

// Compound indexes for common queries
db.jobs.createIndex({ parentCompany: 1, status: 1, scheduledDate: 1 });
db.jobs.createIndex({ parentCompany: 1, assignedTo: 1, status: 1 });
db.jobs.createIndex({ parentCompany: 1, appType: 1, createdAt: -1 });

// Geospatial index for location-based queries
db.jobs.createIndex({ "serviceAddress.location": "2dsphere" });

// Text search index
db.jobs.createIndex({
  title: "text",
  description: "text",
  "client.name": "text",
});

Caching Strategy​

  • Job Lists: Cache frequently accessed job lists by status and assignee
  • Job Details: Cache individual job data for mobile offline access
  • Aggregated Data: Cache dashboard statistics and reports
  • Search Results: Cache common search queries and filters

🔒 Security Considerations​

Access Control​

  • Multi-tenant Isolation: Jobs isolated by parentCompany
  • Role-based Access: Different permissions for managers, dispatchers, field workers
  • Field-level Security: Sensitive data (pricing, customer info) restricted by role
  • Audit Trail: All job modifications logged with user and timestamp

Data Validation​

  • Status Transitions: Validate allowed state changes
  • Business Rules: Enforce industry-specific constraints
  • Input Sanitization: Prevent injection attacks
  • File Upload Security: Validate and sanitize attachment uploads

📈 Analytics and Reporting​

Key Metrics​

  • Job Completion Rate: Percentage of jobs completed successfully
  • Average Completion Time: Time from creation to completion
  • Resource Utilization: How efficiently resources are being used
  • Customer Satisfaction: Based on feedback and ratings

Industry-Specific Analytics​

  • Trucking: Route efficiency, fuel costs, delivery times
  • Service/Repair: First-time fix rate, parts usage, technician productivity

🔗 Related Documentation​