Fire Index — Fire Harvesting Engine & JOS Worker Pipeline

The Fire Harvesting Engine is the distributed data extraction and validation pipeline powering the Fire Safety Index. It coordinates real-time client-side ECSQL queries, backend job ingestion, asynchronous job orchestration (JOS), and high-throughput containerized workers to produce a fully validated Golden Thread database.

Architecture Overview

1. Client-Side Harvest Execution (`FireHarvestingModal`)

When a user triggers Run Fire Harvest in the application:

Active Context Resolution: Resolves the selected iTwinId, iModelId, active changeSetId, and configured Fire Safety Profile.

ECSQL Execution: Runs genuine ECSQL queries directly against Bentley's iModel RPC interface:

SELECT 
  e.ECInstanceId, 
  ec_classname(e.ECClassId, 's.c') AS ClassName, 
  e.UserLabel, 
  e.CodeValue, 
  e.Model.Id AS ModelId,
  e.$->FIREie__x002E__Type__x002E__ResistanceToFireRequiredInsulation AS FireRatingInsulation,
  e.$->FIREie__x002E__Type__x002E__ResistanceToFireRequiredIntegrity AS FireRatingIntegrity
FROM bis.GeometricElement3d e
WHERE e.$->FIREie__x002E__Type__x002E__ResistanceToFireRequiredInsulation IS NOT NULL
   OR e.UserLabel LIKE '%FD30%'
   OR e.UserLabel LIKE '%FD60%'

Payload Sanitization: Strips phantom IDs or mock fallbacks; only genuine element records from the active iModel are submitted.

2. Backend Ingestion (`service-app-validation`)

The request is received by the Validation App Service (infra-service-app-validation-1 running on port 3002):

Route: POST /api/fire/index/:iTwinId/:iModelId
Auth & Scope: Validates Bentley IMS bearer token and checks app authorization license (softwareName=validate).
Enqueuing: Dispatches job metadata to the central JOS Orchestrator via POST http://192.168.178.20:3000/api/jobs.

3. Containerized Processing (`itwin-fire-worker`)

The Job Orchestration System (JOS) manages worker lifecycle using pg-boss:

AutoScaler: Detects pending jobs on the fire_harvest queue and scales up container fire_harvest-<timestamp> from image itwin-fire-worker:latest.
Worker Process:
1. Resolve Assets: Extracts inbound raw assets or re-aggregates chunked staging tables.
2. Fire Rating Validation: Parses values against BS 8644-1 and EN 13501-2 standards using high-performance regex parsers.
3. Issue Detection: Automatically detects statutory anomalies (missing ratings, invalid syntax, uncompartmented barriers).
4. FBS Hierarchy Synthesis: Builds the multi-tier Fire Breakdown Structure (Facility -> Storey -> Compartment -> Component).
5. Thematic Color Mapping: Computes hex color codes for each element (FD30, FD60, FD90, FD120, Unrated).

4. Atomic Database Writes (`fire_db`)

The worker commits all results inside an atomic PostgreSQL transaction into fire_db:

Table Name	Primary Key	Stored Data
`fire_results`	`(id)`	Aggregated FBS hierarchy tree, total asset count, issue summaries, and normalized asset records.
`fire_issues`	`(id)`	Individual statutory compliance issues linked to `imodel_id`, category, and severity.
`fire_color_cache`	`(itwin_id, imodel_id, ec_instance_id)`	Pre-computed hex colors (`thematic_color_hex`, `health_color_hex`) enabling sub-50ms 3D viewport rendering.

5. Status Polling and Completion

The front-end monitors execution through GET /api/fire/index/:iTwinId/:iModelId/status?jobId=...:

{
  "id": "905497fa-fb8e-417d-8c16-9314bdf4699e",
  "queue": "fire_harvest",
  "status": "completed",
  "itwinId": "6e6fbae2-5cdf-45f6-b184-059f274aa7a1",
  "output": {
    "status": "completed",
    "itwinId": "6e6fbae2-5cdf-45f6-b184-059f274aa7a1",
    "imodelId": "6b06558e-ccfd-4976-915c-38446ba50353",
    "harvestRunId": "3a93df9a-c7ce-4ba0-80aa-063444a01f24",
    "totalAssets": 24,
    "totalIssues": 2,
    "fbsHierarchyNodes": 12,
    "durationMs": 3
  },
  "durationMs": "10.890000"
}

Upon completion, the UI automatically updates the tree browser, issues badge counter, and 3D thematic viewport shading.

Fire Index — Fire Harvesting Engine & JOS Worker Pipeline

Architecture Overview

1. Client-Side Harvest Execution (FireHarvestingModal)

2. Backend Ingestion (service-app-validation)

3. Containerized Processing (itwin-fire-worker)

4. Atomic Database Writes (fire_db)

5. Status Polling and Completion

Related Documentation

1. Client-Side Harvest Execution (`FireHarvestingModal`)

2. Backend Ingestion (`service-app-validation`)

3. Containerized Processing (`itwin-fire-worker`)

4. Atomic Database Writes (`fire_db`)