Runtime Topology

One product, five runtime surfaces, clear ownership lines.

The runtime shape is intentionally asymmetric. User-facing requests sit at the edge, repeated orchestration stays near data, and blockchain execution is serialized per vault through a dedicated actor. That shape is what keeps latency, durability, and transaction ambiguity from collapsing into one layer.

Execution Surfaces

Web, Worker, Workflows, Durable Objects, Neon.

Primary DB

Neon

Single relational authority with replica and queue-backed recovery options.

Execution Actor

Per vault

Each Metavault gets serialized blockchain state management.

Edge Cache

A distribution cache, never the freshness or truth authority.

User-facing traffic stays fast at the edge

The web app talks to the Worker through typed HTTP contracts. The frontend never becomes the trusted execution surface.

Durable background work stays close to the database

Workflows handle monitoring, trigger evaluation, refresh jobs, and replay-friendly business logic in a region close to Neon.

Blockchain ambiguity is isolated in a dedicated actor

The TLM owns nonce serialization, submission, receipt ambiguity, and recovery. That responsibility is intentionally not shared with the generic worker layer.

Spec + product contract

Service boundaries are explicit because access control depends on them.

The public contract is Worker-owned. TLM is not a public API. Trigger Registry is not a user-facing query surface. Each route group has a middleware chain and each internal call path has a preferred mechanism.

Path	Mechanism	Reason
Frontend → Worker	HTTPS via typed client	Stable public contract, caching semantics, auth, and rate limiting.
Worker → Workflow	Native invocation	Durable orchestration handoff with explicit backend ownership.
Worker / Workflow → TLM	Durable Object RPC	Direct actor boundary for execution and emergency-close operations.
Worker / Workflow → Trigger Registry	DO RPC with service auth	Live trigger control plane stays internal-only.

Storage semantics

Neon is authoritative, but not every operational read comes from Neon.

The system uses multiple stores, each with a sharply defined role. Neon is the canonical relational store. KV distributes hot reads. Durable Objects own live operational state for execution and trigger continuity. On-chain state remains the final arbiter when drift appears.

Authoritative stores

Neon for canonical product data and analytics.
Trigger Registry DO for current active trigger control state.
TLM DO for in-flight execution state and mirrored encrypted sessions.
On-chain state for ultimate position and account truth during reconciliation.

Support stores

KV for cache distribution and outage-resilient notification delivery metadata.
Queues for deferred writes and bounded replay after outages.
Hyperdrive for pooled edge-to-Neon reads.
Never treat KV as freshness authority or mutual-exclusion state.

2 min Price refresh cadence into KV hot cache.

30 min Market and WorldMonitor enrichment pipeline cadence.

6 hr Cluster and cascade analytics cadence.

Canonical entities

The entity model keeps public data and user-owned data conceptually separate.

The canonical model is product-first: user, smart account, spell, spell cast, position, alerts, trigger, trigger fire, notification subscription, session authorization, and intelligence entities for markets and WorldMonitor.

Package boundaries

The monorepo mirrors the runtime decomposition.

Packages are separated by responsibility so the codebase does not erase the runtime model. Shared contracts and pure business logic stabilize first, then each runtime surface consumes them through explicit boundaries.

`packages/shared`

Schemas, constants, contract types, typed APIs, and shared runtime contracts.

`packages/core` + `packages/db`

Pure business logic, protocol builders, Drizzle schemas, and scoped query modules.

`packages/worker`, `workflows`, `tlm`, `web`

Each runtime surface consumes the shared layers without collapsing into one application boundary.