Core Concepts

This page covers the foundational concepts that underpin the Turqoa platform. Understanding these concepts is essential for configuring, operating, and extending the system.

Decision Engine

The Decision Engine is the central evaluation component that processes enriched data and produces structured decisions. It operates on three core primitives: rules, confidence scores, and modes.

Rules

Rules are declarative condition-action pairs written in Turqoa's policy DSL. Each rule defines a set of conditions that must be satisfied and the resulting action when they are:

rules:
  - name: auto_approve_standard
    priority: 100
    when:
      all:
        - field: ocr.container.confidence
          op: gte
          value: 0.95
        - field: tos.appointment.status
          op: eq
          value: confirmed
        - field: damage.max_severity
          op: eq
          value: none
    then:
      decision: approve
      auto: true
      reason: "All checks passed with high confidence"

Rules are evaluated in priority order. The first matching rule determines the decision. If no rule matches, the transaction is routed to manual review.

Confidence Scores

Every AI perception output includes a confidence score between 0.0 and 1.0. These scores drive rule evaluation and determine whether a transaction can be auto-processed or requires human review:

Decision Modes

Turqoa supports three operational modes that control how decisions affect physical operations:

Warning: Transitioning from Shadow to Live mode should only occur after thorough validation. Use the turqoa analytics accuracy command to review decision quality metrics before switching.

Operator-in-the-Loop

Turqoa's operator model is built on the principle that automation should handle routine cases while humans focus on exceptions. The system routes transactions to operators based on:

• Confidence thresholds — Reads below configured confidence levels require human verification
• Rule exceptions — Transactions that match no auto-approve rule enter the review queue
• Anomaly flags — Unusual patterns (first-time carrier, mismatched seal) trigger review
• Random sampling — A configurable percentage of auto-approved transactions are sampled for quality assurance

Operators interact through the Command Center, which presents:

1. The captured images with AI annotations
2. OCR results with highlighted confidence levels
3. The decision engine's recommendation and reasoning
4. One-click approve/deny with mandatory justification for overrides

Audit Trail and Evidence

Every action in Turqoa produces an audit record. Audit records are immutable, append-only, and cryptographically chained to prevent tampering.

An audit record contains:

{
  "event_id": "evt_9f3a2b1c",
  "timestamp": "2026-04-06T14:32:01.443Z",
  "type": "transaction.decision",
  "transaction_id": "txn_7e4d8a2f",
  "actor": "decision-engine",
  "data": {
    "decision": "approve",
    "mode": "live",
    "auto": true,
    "rules_evaluated": 12,
    "rule_matched": "auto_approve_standard",
    "confidence_scores": {
      "container_ocr": 0.97,
      "plate_ocr": 0.99,
      "damage": 0.02
    }
  },
  "evidence_refs": [
    "img/txn_7e4d8a2f/front.jpg",
    "img/txn_7e4d8a2f/rear.jpg",
    "img/txn_7e4d8a2f/plate.jpg"
  ],
  "chain_hash": "sha256:a3f2e1..."
}

Note: Evidence images are stored alongside audit records and referenced by hash. The chain_hash field links each record to its predecessor, creating a verifiable sequence.

Zones and Geofences

Zones define physical areas within a terminal that have specific monitoring rules. Each zone is a named polygon with associated detection policies:

• Gate zones — Lane-level areas where gate transactions occur
• Restricted zones — Areas requiring authorization for entry
• Monitored zones — Areas under continuous surveillance with alert rules
• Geofenced zones — GPS-defined boundaries for vehicle and vessel tracking

Zones are configured with geographic coordinates and can have time-based activation schedules:

zones:
  - id: zone-restricted-01
    name: "Reefer Yard Section A"
    type: restricted
    polygon:
      - [31.2001, 29.9187]
      - [31.2001, 29.9195]
      - [31.2008, 29.9195]
      - [31.2008, 29.9187]
    schedule:
      active: "00:00-23:59"
      days: ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
    rules:
      - unauthorized_entry
      - loitering_detection

Event-Driven Architecture

Turqoa uses an event-driven architecture where all system components communicate through a central event bus. Events are typed, timestamped, and carry structured payloads:

Common event types:

Events can be consumed by external systems through webhooks or message queue integrations:

# Webhook subscription example
webhooks:
  - url: https://tos.example.com/turqoa/events
    events:
      - decision.produced
      - operator.override
    auth:
      type: bearer
      token_env: WEBHOOK_TOKEN
    retry:
      max_attempts: 3
      backoff: exponential

Shadow, Advisory, and Live Modes

These three modes deserve additional explanation as they form the foundation of Turqoa's safe deployment model.

Shadow mode runs the full pipeline — perception, validation, decision — but takes no physical action. Barriers remain under manual control. This mode is used during initial deployment to validate that the system produces correct decisions before granting it control authority.

Advisory mode displays decisions to operators as recommendations. The operator sees what Turqoa would do and can choose to follow or override the recommendation. This mode builds operator trust and provides training data for rule refinement.

Live mode grants the system authority to actuate barriers and update the TOS directly for auto-approved transactions. Manual review transactions still require operator action. Live mode can be scoped per lane, allowing gradual rollout across a terminal.

# Set mode per lane
turqoa config set decision.mode advisory --site "my-terminal" --lane 01
turqoa config set decision.mode live --site "my-terminal" --lane 02