Architecture Overview

Goal

Build a single Python app with strict internal boundaries between data gathering and execution. The backbone should support clean messaging, risk controls, and observability, while remaining simple to run locally and on Ubuntu.

Terminology (Canon)

Cornice uses a consistent naming model across docs, code, and schemas:

• Exchange: the platform/company (Polymarket, Kalshi).
• Venue: Cornice-internal alias for Exchange (used in logs and fields).
• Market: the event definition + resolution rules (cross-venue concept).
• Contract: the tradable instrument for a specific Outcome (venue-specific).

High-Level Flow

1. Ingest: Kalshi + Polymarket REST/WS clients pull market and orderbook data.
2. Normalize: Convert platform-specific payloads into a common schema.
3. Signal: Publish signals and state changes to RabbitMQ and emit UI updates via socket.io.
4. Decide: Strategy engine scores opportunities (initially rule-based; Inkwell later).
5. Execute: Order manager places trades, tracks fills, and updates positions.
6. Persist: Store market mappings, orderbooks (optional), positions, and P&L in Postgres.

Boundaries (Strict Modules)

• data/: Market discovery, data ingestion, normalization, caching, and signal publishing. No order placement.
• execution/: Order placement, fill tracking, position/P&L, risk/circuit breaker. No direct API polling.
• strategy/: Signal scoring and selection. Pure logic; no network.
• infra/: Postgres, RabbitMQ, socket.io, config, logging, metrics.
• api/: FastAPI HTTP endpoints (health, config, admin) and socket.io integration.

Runtime Model

• Single process with async tasks for data ingest and execution loops.
• RabbitMQ is the internal message bus (replaces Redis pub/sub).
• Postgres is the source of truth for positions and audit logs.

Later Phase (Inkwell)

• Strategy module can call Inkwell to score or rank opportunities.
• Inkwell stays read-only until execution safety is mature.