# Architecture concepts

Product design

This page describes the product model and requirements. Examples illustrate the model, not a guaranteed API or completed feature. Check the [application contracts](/stormtrust/apps/) and [dataset inventory](/stormtrust/product/platform-and-data/datasets-and-source-contracts/) for implemented scope. Use [operations guides](/stormtrust/engineering/operations/) for runnable procedures.

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

```txt
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:

```json
{
	"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:

```json
{
	"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:

```txt
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:

```txt
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:

```json
{
	"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:

```txt
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](/durable-objects/) for coordinated state rather than generic stateless request handling.