Module & Directory Layout

Proposed Structure

app/
  main.py                # app entrypoint; wires HTTP + socket.io + tasks
  api/
    http.py              # FastAPI routes (health, config, admin)
    socketio.py          # socket.io server setup + event emit helpers
  data/
    clients/
      polymarket.py      # REST/WS client
      kalshi.py
    ingest.py            # fetch loops + scheduling
    normalize.py         # platform -> normalized model
    mapping.py           # cross-market mapping logic
  strategy/
    scorer.py            # rule-based scoring for opportunities
  execution/
    orders.py            # order placement (later)
    positions.py         # position + P&L tracking (later)
    risk.py              # circuit breaker (later)
  infra/
    db.py                # Postgres connection/session
    mq.py                # RabbitMQ publish/consume
    settings.py          # env config
    logging.py           # structured logging setup
  models/
    market.py            # normalized dataclasses/Pydantic models
    signals.py
    events.py
scripts/
  run_local.sh
docs/

Strict Boundaries

• data/ reads external APIs and writes normalized events.
• strategy/ reads normalized events and emits signals.
• execution/ reads signals and handles orders (later phase).
• infra/ has no business logic; it only provides plumbing.

Growth Paths

• Add data/clients/{new_market}.py and data/normalize.py mappings.
• Add new signal types in models/signals.py and strategy/scorer.py.