Architecture

Five npm packages and two services, each with one job. What every package is for, which ones you install, and how Connect sits between the chain and your venue.

The shape

        chain (Somnia)
             │
    indexer  │  raw truth: markets, trades, balances, resolutions
             ▼
    ┌────────────────────┐
    │  connect-api       │  data plane  — projections, reads, realtime fan-out
    │  connect-gateway   │  control plane — login, sponsorship gate
    └────────────────────┘
             │  the wire (one contract, both sides)
             ▼
    connect-sdk → connect-react → venue-kit
             │
             ▼
      your venue · prophecy.social · Studio venues

Two rules this diagram encodes, both worth knowing before you build:

Ingest once, project per venue, serve cached. Venue number two doesn’t add a pipeline; it adds a projection and a cache namespace.
Control plane ≠ data plane. Login and sponsorship live in a separate service from reads, so a paymaster incident can never take your market pages down.

The packages

You install the top two. The rest are what they’re built from — worth knowing so you can tell where a type or a number came from.

Package	What it is	Do you install it?
`@prophecy-dev/connect-react`	The hooks: `<ConnectProvider>`, `useEvents`, `useOdds`, `useActivity`, `useSearch`, `useLiveStats`, `useLeaderboard`, `useWallet`, `usePositions`, `useResolution`, plus `<LiveTrades>`/`<TradePulse>` and the `{c}` checkout drawer.	Yes, if you’re on React.
`@prophecy-dev/connect-sdk`	The framework-neutral client: typed reads over HTTP (cached) and realtime over one multiplexed WebSocket. Also `ConnectAuth` (sessions) and the predict helpers.	Yes — directly if you’re not on React, as a peer of `connect-react` if you are.
`@prophecy-dev/venue-kit`	The venue itself: `VenueShell`, `MarketGrid`, `MarketCard`, `MarketDetail`, `CategoryNav`, `Leaderboard`, `PositionsTable`, search and browse — plus the headless hooks and the `--pc-*` token contract. Structure, not brand.	If you’re building a whole venue rather than embedding a piece.
`@prophecy-dev/connect-wire`	The contract: shared types and every read/stream definition, implemented by both the SDK and the API. You rarely import it — you depend on it through the SDK.	Transitively.
`@prophecy-dev/connect-core`	The pure fold: trades → positions with cost basis → PnL. BigInt-exact, no IO. Run by the server and the client, so the numbers are identical by construction.	Transitively.

Why the split matters:

wire exists so client and server can’t drift. One declaration, two implementations — a changed response shape becomes a type error at your build, not a wrong number in production. → The wire
core exists so a number has one definition. Never re-derive PnL in a frontend; ask for it. → Derive once
sdk vs react — same client, one with hooks. → sdk or react
venue-kit exists so behaviour isn’t re-implemented per venue — including the rules that bite, like tradeable ≠ un-resolved. → Structure vs skin

Not everything ships as a package

There’s also a shadcn registry at cdn.prophecyhosting.com/r/*.json — VenueShell, MarketCard, a browse-page block and per-venue themes as Tailwind v4 source you install with npx shadcn@latest add <url> and then own.

It’s an option, not the path. The npm packages need no styling stack, and Studio’s generated venues skin the kit with plain CSS over its --pc-* tokens rather than using the registry. Take the blocks if you’re already on Tailwind and want editable markup.

What doesn’t vary: anything touching the trade handler stays on npm, versioned and un-forkable. Copied code silently drops wiring, and a money path is the wrong thing to re-implement by accident — so skins are copyable and the trade path isn’t. → Structure vs skin

The services

Service	Plane	What it does
`api.prophecyhosting.com`	data	Reads, search, projections, and the realtime relay. Edge-cached.
`gateway.prophecyhosting.com`	control	Login (SIWE + Privy) and the sponsorship gate that decides whether a user’s action is paid for.

Both run on Cloudflare Workers with Durable Objects for the stateful parts — one relay per stream, one hub per venue.

The neighbours

Connect isn’t the whole stack. What sits either side of it:


Somnia Markets	The market contracts. Today’s markets are CPMM, keyed by `conditionId`; an order-book (CLOB) structure is live on both networks with its own market id, so treat a market’s id as opaque and branch on structure, never on a version. Your venue id is a routing and fee tag on the trade.
Prophecy Facts (`prophecy-oracle`)	Resolution. Markets are AI-resolved against declared sources; the oracle carries the question, its sources and the answer graph. Connect reads it — see Resolution.
The indexer	Envio → GraphQL, maintained alongside the chain. It owns raw truth; Connect never re-indexes it, and stores projections plus a cursor.
Prophecy Social	`prophecy.social` — a venue on Connect, with no crons, chain access or derivation of its own.
Prophecy Studio	Prompt-to-venue. Generates the skin over `venue-kit`; everything with a formula or money in it is a call into Connect.

What they’re built on

Deliberately little. The npm packages depend on viem and zod and nothing else — no CSS framework, no component library, no state manager. They’re ESM-only, and connect-sdk is runtime-neutral (no window, no document), so it runs in a browser, a Worker, or a server process unchanged.

The only place a styling stack is assumed is the registry blocks (Tailwind v4 + the shadcn CLI), and those are opt-in — a venue can be built, themed and shipped without them. Full requirements and where each piece runs are in Get started.

Versioning

The packages are 0.x, so a caret pins to the minor. connect-sdk and connect-react declare the wire range they implement — keeping those in step is the supported path, and upgrading them together is what turns a contract change into a compile error instead of a surprise.