Skip to content
Developer Docs

Architecture concepts

Last updated View as MarkdownAgent index

StormTrust follows a weather-to-action lifecycle. Every stage remains independently inspectable:

Forecast intelligence
        │
        ▼
Radar evidence
        │
        ▼
Ground observations
        │
        ▼
Evidence fusion
        │
        ▼
Storm event and revision
        │
        ▼
Hail swath
        │
        ▼
Property intersection
        │
        ▼
Impact assessment
        │
        ▼
Prioritization
        │
        ▼
Action plan
       / \
      ▼   ▼
   Field  Campaign
      \   /
       ▼ ▼
      Outcome
        │
        ▼
    Attribution

Evidence and confidence

Evidence classification

Every meaningful weather or impact claim carries a classification:

Label Meaning
predicted Forecast-oriented future expectation
radar-derived Result derived from radar or radar-composite data
modeled Result produced by an algorithm or inference model
report-observed Result based on an external observation or report
field-confirmed Result confirmed by an authorized field workflow
human-reviewed Result reviewed by a qualified human
third-party-verified Result verified by an approved independent party

A record may contain several evidence items. A displayed summary label must not destroy the individual lineage.

Confidence and evidence type

Confidence and classification are separate dimensions:

{
	"classification": "radar-derived",
	"confidence": 0.91
}

Confidence answers how strongly StormTrust supports a conclusion. Classification answers what type of evidence supports it.

Confidence components

Future confidence models may use radar quality, source agreement, spatial and temporal agreement, ground support, algorithm reliability, and data completeness. Every operational formula must be versioned through an algorithm release.

Illustrative formulas must not appear as approved operational algorithms.

Provenance

Every important derived record should be traceable:

{
	"derivedObjectId": "impact_123",
	"algorithmRelease": "impact-v1.3.0",
	"eventRevision": 4,
	"sources": [
		{
			"source": "noaa-mrms",
			"asset": "CONUS/MESH/...",
			"observedAt": "2026-08-16T19:14:00Z",
			"acquiredAt": "2026-08-16T19:16:07Z"
		}
	]
}

Provenance supports debugging, customer trust, historical replay, audits, algorithm comparison, corrections, reports, and third-party review.

Storm events and revisions

A StormEvent is a durable identity. A StormEventRevision records evolving understanding:

StormEvent: ST-2026-08-16-KC-001

Revision 1
Estimated 1.25 in hail.

Revision 2
Estimated maximum increases to 1.75 in.
Boundary expands northeast.

Revision 3
Ground report records 1.50 in hail.

Revision 4
Event swath reconciled.

Revision 5
Property impacts recalculated.

Downstream systems identify which revision informed an action.

Property impact

Property impact follows a deliberate progression:

Property
   ↓
Parcel
   ↓
Structure
   ↓
Roof
   ↓
Storm exposure
   ↓
Damage likelihood
   ↓
Confidence
   ↓
Opportunity
   ↓
Eligibility
   ↓
Priority

Exposure means a property intersects or sits near storm evidence. Damage likelihood estimates whether conditions could produce relevant damage. Opportunity represents business value. Eligibility determines whether an action is allowed. Priority orders eligible opportunities.

Action plans

An action plan translates intelligence into recommended operations:

{
	"eventId": "ST-2026-08-16-KC-001",
	"revision": 3,
	"strategy": "field-deployment",
	"zones": [
		{
			"name": "Northwest",
			"priority": 1,
			"candidateProperties": 381,
			"assignedCapacity": 4
		}
	]
}

Action plans are versioned, explainable, editable, reviewable, freezeable, and comparable against outcomes.

Outcomes and attribution

StormTrust connects actions to results:

Storm event
   ↓
Property impact
   ↓
Action plan
   ↓
Assignment
   ↓
Visit or campaign
   ↓
Lead
   ↓
Inspection
   ↓
Opportunity
   ↓
Signed job
   ↓
Revenue

Attribution supports event, property, territory, salesperson, campaign, channel, tenant, source, and algorithm-release analysis.

Multi-tenancy

Every tenant-owned object has a clear tenant boundary. Isolation applies to database queries, object keys, caches, queue messages, Durable Object addresses, exports, reports, tokens, webhooks, audiences, contact data, and audit history.

Tenant context is explicit. StormTrust does not infer authorization from a client-controlled identifier alone.

Real-time state

StormTrust uses coordinated state only when coordination is required. Potential Durable Object responsibilities include a live storm actor, collaborative territory state, WebSocket fan-out, live revision distribution, and controlled single-writer transitions.

Use Cloudflare Durable Objects for coordinated state rather than generic stateless request handling.

Developer Docs