geointel/docs/JOB_LIFECYCLE_CONTRACT.md

Job Lifecycle Contract

GeoIntel uses background jobs for long-running geospatial and AI tasks.

Status Values

• queued: job record exists but worker has not started.
• running: worker is processing.
• completed: output persisted and metrics available.
• failed: processing stopped with a recoverable or unrecoverable error.
• cancelled: user requested cancellation before completion.

Common Job Fields

• id
• project_id
• job_type
• status
• progress_percent
• current_step
• parameters_json
• result_json
• error_json
• created_at
• started_at
• finished_at

Job Types

• raster_metadata
• raster_clip
• raster_tile
• vector_metadata
• vector_clip
• object_detection
• segmentation
• qaqc
• export_geojson
• export_report

Progress Steps

Object detection should use these steps:

1. validate_input
2. prepare_tiles
3. load_model
4. run_inference
5. georeference_outputs
6. persist_results
7. calculate_metrics
8. completed

Error Contract

A failed job must store:

{
  "code": "RASTER_CRS_MISSING",
  "message": "Raster CRS could not be determined.",
  "recoverable": true,
  "step": "validate_input"
}

Frontend Behavior

• queued: show pending state.
• running: show current step and progress.
• completed: show outputs and actions.
• failed: show error, details and retry where safe.