← Patterns

Engineering onboarding · 55 minutes

Build the right model of Northwind Ingestion before you operate it

Read the current path, learn where familiar queue assumptions fail, run one event locally, and finish with the questions worth asking on your first on-call review.

Audience: incoming platform engineerEnvironment: local onlyOwner: PlatformOutcome: explain, run, verify

Learning goal · 55 minutes

By the end, you can

01

The working model

8 min

Northwind Ingestion is an internal acceptance and landing path. Producers send events to the gateway; one shared queue buffers them; consumers validate and write them to the warehouse.

Carry this sentence: the current queue is both the buffer and the failure boundary for every first-party producer.

Ingestion architecture Producers enter through a gateway inside the trust boundary, buffer in a queue, and are consumed into the warehouse. The queue is the only component without a failover, and it carries the whole ingestion path. TRUST BOUNDARY async Producers Gateway :8443 Queue single instance Warehouse no failover LEGEND dashed: outside Platform accent: single point of failure

The diagram also shows the proposed dispatcher and split queues. Those components are not production facts yet; they belong to RFC 014.

02

Four boundaries that prevent wrong assumptions

12 min

Acceptance

202 is queued, not warehoused

Lookup and freshness are later concerns. Do not promise downstream visibility at gateway acceptance time.

Identity

Event ID is the retry anchor

Reuse it. A new ID turns a retry into a second logical event.

Ordering

Producer-local order is not guaranteed

The proposed split does not remove a promise because that promise does not exist today.

Rollback

Queues are retained, never deleted

Cutovers flip traffic. Destructive queue actions are not a rollback strategy.

If a design or incident response crosses one of these boundaries, stop and open the owning contract or runbook before acting.

03

Read the request path without running it

12 min
httpPOST /events
X-Request-Id: req_7f3

{"id":"evt_01","type":"checkout.paid"}

202 {"id":"evt_01","status":"accepted"}
Follow three values through code: event ID for idempotency, request ID for tracing, and status for caller behavior.

Then read configuration in this order: required queue URI, bind address, health endpoints, and alert thresholds. The reference page owns exact keys; onboarding owns the mental path through them.

04

Run one event locally

15 min

  1. Run the tests

    bashmake ingest-test

    Success: contract and consumer tests pass.

  2. Start the gateway

    bashmake ingest-run

    Success: the log contains listening on 8443.

  3. Post the synthetic event

    bashcurl -k https://127.0.0.1:8443/events \
  -d '{"id":"evt_learn","type":"onboarding.ping"}'

    Success: 202 repeats evt_learn.

05

Prove readiness with understanding, not task completion

8 min

You are ready for the next document when: you can explain what is current, proposed, unresolved, and safe to change without relying on memory or access to production.