Integration layer between suppliers and marketplaces.

System architecture · data flow

How a product becomes a priced, sellable listing

The full picture. Suppliers feed in on the left; the core normalizes, merges, prices, and publishes; marketplaces receive listings on the right; orders & returns flow back; the system of record captures every event underneath.

Reading it: an offer is normalized to the canonical model, merged into a Master Product, priced once by the central engine, then published to every active marketplace. No connector ever computes price. Sourcing is decided at order time from the freshest cost & inventory.

The isolation guarantee

Why a change in one module can't break another

# Dependency direction — always inward, never sideways

  modules/pricing
      │  depends on
      ▼
  contracts/pricing   # interfaces + events
  contracts/catalog   # reads offers via contract
      │
      ▼
  common              # primitives only

# ❌ what CI forbids
from ridewell.modules.catalog._internal import ...

# ✅ what's allowed
from ridewell.contracts.catalog import CatalogQuery
from ridewell.common.money import Money

Repository layout

One monorepo, clear physical structure

src/ridewell/
  common/              # primitives: ids, errors, config, logging, money, event envelope, secrets
    jobs/              # shared job envelope + status + retry / idempotency metadata
  contracts/           # interfaces + domain events — the only cross-module language
    catalog/  pricing/  orders/  suppliers/  marketplaces/
  modules/             # isolated domains — each owns its tables, job handlers, DESIGN.md, tests
    supplier_adapters/  catalog/  pricing/  orders/
    marketplace_connectors/  system_of_record/  scheduler/
  apps/                # thin process entry points wiring modules together
    api/        # FastAPI + auto-generated Swagger / OpenAPI
    worker/     # executes queued jobs → dispatches to the owning module's handler
    scheduler/  # decides WHEN: polling + recompute triggers (enqueues only)
tests/                # unit · property · integration · contract · e2e · import-boundary
deploy/               # Dockerfile · docker-compose
docs/                 # this page + per-module DESIGN.md

Modules

Nine modules, one shared contract layer

Each module owns its tables and behaviour and ships its own DESIGN.md. The depends on column lists the only packages it may import — enforced in CI.

Documentation

Per-module DESIGN.md template

Defined before implementation so every module is documented the same way. Each section is what an engineer — or an AI agent — needs to work on the module without reading the whole codebase.

# <module_name>

## Purpose            # what this module is for, in two sentences
## Owns               # tables, behavior, and decisions it is responsible for
## Does Not Own       # explicit non-responsibilities (prevents scope creep)
## Public Contracts   # interfaces it exposes in contracts/<domain>
## Events Emitted     # event types + idempotency key source
## Events Consumed    # event types it handles + inbox dedup rule
## Tables Owned       # schema + ownership boundary
## External APIs Called # supplier / marketplace endpoints, auth, rate limits
## Config / Secrets    # env + SecretsProvider keys it needs
## Invariants         # statements that must always hold (encoded as tests)
## Failure Modes      # what can go wrong and the expected behavior
## Retry / Idempotency # keys, backoff, dead-letter conditions
## Metrics            # what it emits for observability
## Tests Required     # unit / property / integration / contract / golden flow
## AI Usage Notes     # how an agent should call it; safe vs unsafe operations

Sourcing

Sourcing is decided at order time

Multiple suppliers carry the same product. Each is kept as a distinct Supplier Offer under one Master Product. Sourcing uses the most recent cost and inventory, not the values at listing time.

Pricing engine

Five stages, in order

Price is computed once per Master Product per marketplace. Connectors publish this price; they do not compute their own. Every stage is recorded so a price can be reconstructed.

Markup resolution

Most-specific rule wins

Data model

Entities, types, and keys

Each entity lives in its owning module's Postgres schema. PK primary key · FK foreign key · UQ unique. Types are indicative; final DDL is the engineering team's call.

Testing

Test layers and invariants

Every layer below is a CI gate. The invariants on the right are encoded as tests and must hold on every build.

Stack

Libraries

Simulators

Fakes that implement the real contracts

All four suppliers are still TBD on API-vs-FTP. To build and test the whole architecture before credentials arrive, every external integration has a fake that implements the same contract as the real one — so a fake is a drop-in swap, not a separate code path.

Process roles

One image, three process roles

The same container runs in one of three roles, selected by an entrypoint flag. Monolith today; any module can be split into its own service later without code changes, because the contracts already abstract in-process versus HTTP calls.

Reliability

Outbox, inbox, and idempotency

Applied at async and external boundaries — anything that crosses the job queue or calls an external system. Synchronous in-process contract calls inside one request do not need this.

Cross-cutting

Data, secrets, and observability

Non-functional targets

Targets

Build sequence

Foundation-first. No big bang.

Each phase is independently shippable and fully tested before the next begins. Supplier and marketplace integrations are deliberately not touched until the foundation, audit spine, and ingestion framework exist.