# Application architecture

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.

This page explains the repository, runtime choices, and target replay experience. For a working first result, use [Build your first Worker](/stormtrust/engineering/operations/first-worker/) or [Run the local application stack](/stormtrust/engineering/operations/local-development/).

## Repository model

StormTrust manages organization infrastructure and applications from a shared infrastructure repository:

| Layer                                         | Owner     | Canonical location |
| --------------------------------------------- | --------- | ------------------ |
| GitHub organization                           | Terraform | org/github/        |
| Cloudflare account and zones                  | Terraform | org/cloudflare/    |
| Application code and deployment configuration | Wrangler  | org/apps/          |
| Shared infrastructure lifecycle modules       | Terraform | org/modules/       |

Terraform owns durable infrastructure lifecycle. Wrangler owns application deployments and application-bound runtime configuration.

For the implemented contributor workflow, refer to [Pull request workflow](/stormtrust/engineering/github/pull-request-workflow/).

## Application framework

Applications run on Cloudflare Workers. Plain Workers use the shared root toolchain; framework applications keep the build integration they need. The [Pioneer acceptance canary](/stormtrust/apps/stormtrust-pioneer/) exercises Pioneer compilation, models, queues, and scheduled work. Pioneer is not a prerequisite for creating a StormTrust Worker.

StormTrust documentation does not reproduce the Pioneer framework manual. Pioneer documentation remains authoritative for framework behavior.

## Platform runtime

StormTrust deploys to the Cloudflare developer platform:

| Primitive             | StormTrust responsibility                               |
| --------------------- | ------------------------------------------------------- |
| Workers               | HTTP execution, API endpoints, and application compute  |
| D1                    | Relational durable application state                    |
| R2                    | Weather objects, evidence, exports, reports, and photos |
| Durable Objects       | Coordinated live state with a globally unique actor     |
| Queues                | Asynchronous processing and decoupled work              |
| Workflows             | Durable multistep operations that survive retries       |
| KV and Cache          | High-speed derived or cacheable reads                   |
| Workers AI            | Optional serverless model inference                     |
| Static Assets and CDN | Browser application assets and public content           |

Use the [Cloudflare platform reference](/stormtrust/cloudflare-reference/) for platform behavior that is not specific to StormTrust.

## Release 1 client architecture

Release 1 targets one responsive full-stack web application for desktop and mobile browsers. It does not require a Progressive Web App or native desktop and mobile applications.

The architecture should not prevent future Tauri desktop or mobile shells.

## Local development goals

A local environment should support:

- application startup
- D1-compatible local state
- object-storage fixtures
- queue consumers and scheduled ingestion
- historical event replay
- deterministic test fixtures
- browser development
- API contract validation

Local development should not require live storm data for every test.

## Configuration classes

### Application configuration

Application configuration includes environment, application URL, tenant defaults, and feature flags.

### Weather configuration

Weather configuration includes enabled sources, polling intervals, product catalogs, hail thresholds, and source-lag tolerances.

### Property configuration

Property configuration includes provider selection, permitted field usage, cache duration, and enrichment policy.

### Alert configuration

Alert configuration includes hail and confidence thresholds, watched geography, quiet periods, and notification channels.

### Campaign configuration

Campaign configuration includes supported channels, consent and suppression rules, approval requirements, and spending limits.

## Target quickstart

The canonical quickstart will use a frozen historical fixture:

```txt
fixture
   ↓
source asset
   ↓
decode
   ↓
normalize
   ↓
evidence
   ↓
storm event
   ↓
event revision
   ↓
hail swath
   ↓
sample property intersection
   ↓
impact assessment
   ↓
map
```

A complete product replay command remains a design requirement. It should load frozen inputs, record source metadata, pin an algorithm release, compare expected outputs, and expose the event locally. The existing data service has [a bounded MRMS backfill contract](/stormtrust/product/platform-and-data/live-revisions-and-historical-evaluation/); that contract does not implement the entire property-to-outcome workflow.