On This Page

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

5

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

KV

A distribution cache, never the freshness or truth authority.

Web Next.js + wallet UX Worker API, auth, edge reads Workflows Durable orchestration TLM DO Serialized per Metavault Neon Relational truth

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.

User Metavault Spell Trigger Position Alerts Session Auth Market Data WorldMonitor Notifications
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.