The Problem In One Sentence

Cold-chain disputes are not only about tracking where a shipment went. The hard problem is proving what happened, who had custody, which rule applied, whether the data can be trusted, and what evidence supports the claim.

That makes ColdTrack a claims intelligence system, not a fleet tracking dashboard.

Evidence Of The Workflow Problem

The visual model above shows the core product argument: rejected shipments create disputes when operational facts are fragmented.

ColdTrack responds by turning each disputed fact into a domain surface:

| Disputed fact | System response | | --- | --- | | Who held the goods? | Custody chain with non-overlapping windows | | Which rules applied? | Immutable contract snapshot per shipment | | What happened in transit? | Observation timeline from manual, CSV, API, or IoT inputs | | Can the data be trusted? | Data quality assessment and anomaly detection | | Who is responsible? | Deterministic diagnosis with decision trace | | What should be sent to the counterparty? | Versioned evidence package and claim workflow |

Design Decision

ColdTrack separates shipment movement from claim responsibility.

The shipment module owns status and legal possession. The diagnosis module does not mutate shipment state; it reads finalized facts from custody, contracts, observations, inspections, and data quality.

That separation matters because a rejected shipment should not automatically imply fault. Fault only becomes meaningful after rules and evidence are evaluated against the custody chain.

Architecture Decision

The backend is shaped as a modular monolith instead of early microservices.

That choice fits the current product stage because the domain is broad but the workflows are tightly connected. The architecture still keeps boundaries explicit through modules such as:

• shipmentcustody
• contractscompliance
• observationsinspections
• dataqualitytrust
• diagnosis
• evidence
• claimsworkflow

The important engineering signal is that the modules are not just folder names. The codebase includes public query contracts, outbox events, command idempotency, integration tests, and architecture rules to protect the boundaries.

Diagnosis Is A Reproducible Process

The diagnosis lifecycle has a clear dependency chain:

sequenceDiagram
    autonumber
    participant QA as QA inspector
    participant Shipment as Shipment custody
    participant Contract as Contract snapshot
    participant Obs as Observations
    participant Quality as Data quality
    participant Diagnosis as Diagnosis engine
    participant Evidence as Evidence package
    participant Claim as Claims workflow
 
    QA->>Shipment: Reject shipment after delivery
    Shipment->>Diagnosis: Trigger diagnostic run with finalized custody chain
    Diagnosis->>Contract: Load immutable SLA rules for shipment
    Diagnosis->>Obs: Load observations and inspection records
    Diagnosis->>Quality: Load confidence score and anomalies
    Diagnosis->>Diagnosis: Evaluate rules inside custody windows
    alt Evidence supports attribution
        Diagnosis->>Evidence: Publish verdict, party attribution, decision trace
        Evidence->>Claim: Attach reproducible package to claim
    else Evidence is incomplete
        Diagnosis->>Evidence: Publish Unknown attribution with missing-evidence reasons
        Evidence->>Claim: Open review with evidence gaps
    end

This is the difference between a dashboard and a decision system. A dashboard shows data. ColdTrack is designed to explain why the data leads to a specific claim action.

Responsibility Is Not Guessed

A key rule in the project is that responsibility cannot be invented.

If evidence proves the carrier was responsible during a custody window, the verdict can attribute responsibility to that party. If the evidence is incomplete, the remaining attribution belongs to Unknown.

That design is valuable because it prevents the system from pretending certainty. It also creates a clean future boundary for AI: AI can summarize evidence, highlight missing documents, or draft claim language, but the actual fault decision remains deterministic.

Evidence Package Design

The evidence package is the audit artifact.

It is designed to include the shipment summary, product and batch references, network participants, custody timeline, observations, inspection records, contract rules, data quality warnings, diagnostic verdict, responsibility attribution, loss estimate, claim status, and package checksum.

That turns ColdTrack into a platform for reproducible business decisions rather than a set of CRUD screens.

Trade-Offs

Modular monolith first

The domain has many contexts, but the product does not need distributed infrastructure yet. A modular monolith keeps transaction and deployment complexity lower while still preserving boundaries.

Deterministic rules before AI

AI would be attractive for summarization, but using it to assign fault would weaken auditability. ColdTrack keeps the diagnostic engine deterministic so every verdict can be explained.

Evidence versioning

Immutable evidence packages create more persistence work, but they make audits, disputes, and claim revisions safer. If facts change, the system creates a new evidence version instead of rewriting the old one.

What This Case Study Demonstrates

ColdTrack demonstrates system architecture around business truth:

• modeling custody as a legal possession timeline;
• freezing contract rules for later audit replay;
• separating observations from data quality;
• generating deterministic verdicts with decision traces;
• preserving evidence as immutable, versioned packages;
• using module boundaries to keep a large domain understandable.

The engineering point is that the system does not merely store shipment data. It structures the facts needed to defend a claim.