Engineering reference: the referral tracker architecture

The architecture, for engineers

This is the same system as Part 1 with the friendly labels removed and the real resources named. Everything is in one region, eu-west-2 (London), in one account. There is no API Gateway, no NAT Gateway, and nothing always-on; the only inbound surface is one Lambda Function URL that both redirects link clicks and receives the store’s webhooks, outbound messaging goes through SNS and SES, and slow work is buffered on a single SQS queue.

Lambda functions

Six functions, all Python 3.14 on arm64, all with CloudWatch Logs at 7-day retention. Each does one job and hands off; the SQS queue (rft-jobs, with rft-jobs-dlq as its dead-letter queue after five attempts) decouples the store’s webhooks from the slower model, ledger, and store-API calls. The link redirect is the one path that is not queued — it runs synchronously inside rft-edge so the click is logged and the 302 returned in milliseconds.

• rft-edge — the only public surface. Backs the single Lambda Function URL and handles three event kinds. For a link click (GET /r/{code}): resolves the code in rft-codes, writes a row to rft-clicks, sets the attribution token, and returns a 302. For a sign-up or conversion webhook: verifies the provider signature against the secret, and enqueues a typed job on rft-jobs. For a mint request: enqueues a mint job. Nothing slow happens here.
• rft-minter — SQS-triggered on mint jobs. Reuses the customer’s active code via the rft-codes referrer GSI or claims a new one with a conditional write, pins the reward terms and window, makes the single Bedrock call for the invite, injects the real URL, and returns the link.
• rft-attributor — SQS-triggered on sign-up jobs. Reads rft-clicks for the most recent valid click within the window, resolves the referred person to a durable identity, calls rft-screen, and opens a pending item in rft-referrals (or leaves the sign-up unattributed).
• rft-rewarder — SQS-triggered on conversion jobs. Flips the referral pending → rewarded with a conditional write, re-checks rft-screen, writes one entry per side to rft-rewards, calls the store reward API to fulfil, makes the single Bedrock call for the two thank-you notes, and sends via SNS or SES.
• rft-screen — invoked synchronously by the attributor and rewarder. Runs the deterministic self-referral, duplicate, and velocity checks over rft-referrals, rft-clicks, and the identity fields; returns block / hold / pass, and on a hold emails your team via SES with the rule that fired and the evidence.
• rft-sweep — scheduled. Queries rft-referrals for pending items whose window has elapsed with no conversion and marks them expired, so a code shared into the void is tidied away rather than lingering as an open liability.

Data stores, schedules, and messaging

• DynamoDB (all on-demand). rft-codes — PK code, with a GSI on referrer_id to find a customer’s active code; holds the owner, the pinned reward terms and window, and a status (active / retired). rft-clicks — PK attribution_id (the token), SK click_ts, with a TTL equal to the window so expired clicks vanish and can’t attribute; queried newest-first for last touch. rft-referrals — PK referred_id (the referred person’s durable identity), one item per referred customer so repeat sign-ups collapse to one; carries referrer_id, code, state (pending / rewarded / held / rejected / expired), the pinned terms, and the identity fingerprints. rft-rewards — PK referral_id, SK side (referrer / friend), the exactly-once ledger of what was actually paid. rft-audit — PK event_id, SK ts, append-only, holding each event and the facts a decision was made on.
• Function URL. One, on rft-edge, with provider signature verification in-function for the webhooks; AuthType NONE at the edge because authenticity is enforced by the shared secret, not by IAM, and the redirect route is public by nature. No API Gateway.
• SNS and SES. SNS sends the reward-confirmation SMS where a mobile is the contact; SES sends the invite (if delivered by the business rather than pasted by the customer), the thank-you emails, and the fraud-review email to the team from a verified domain with DKIM.
• EventBridge Scheduler. One rule — rft-sweep at rate(1 hour), expiring pending referrals past their window; the granularity is loose because expiry is not time-critical.
• Secrets Manager. Two secrets — the webhook signing secret and the store/reward API key — fetched at call time, never in env vars or the settings doc.
• Bedrock. Model id anthropic.claude-haiku-4-5 via the Global cross-Region inference profile, invoked only by rft-minter and rft-rewarder.

Exactly-once and failure handling

Two properties carry the whole design, and both are enforced by DynamoDB conditions rather than by hope. Codes are unique because minting claims each with attribute_not_exists(code); a collision fails the write and the minter draws again. Payouts happen once because the rewarder flips rft-referrals from pending to rewarded under ConditionExpression state = pending; the first conversion webhook wins the flip, and any duplicate finds the condition false and stops before touching the ledger. Keying rft-referrals on the referred person’s durable identity does the third piece of work — the same human signing up under many emails resolves to one item, so they can only ever be rewarded once. The rft-rewards ledger adds belt-and-braces with a conditional put per (referral_id, side).

Failure handling is ordinary and boring, which is the point. The webhook-driven work runs from rft-jobs; a handler that throws is retried by SQS and, after five attempts, parked in rft-jobs-dlq for inspection rather than lost or looped. The store reward API is called after the ledger write, so a fulfilment that fails can be retried idempotently against a ledger that already knows the payout is owed — the credit is never double-issued because the ledger, not the API call, is the source of truth. Bedrock is best-effort on both paths: if the invite or thank-you call is slow or errors, a fixed template goes out and the referral is unaffected, because the model only ever wrote words.

IAM scope and region

Each function gets its own execution role scoped to exactly what it touches, no wildcards. rft-edge can read rft-codes, write rft-clicks, read the signing secret, and send to rft-jobs — it cannot call Bedrock, SNS, or the store API, and it cannot touch rft-referrals or the ledger. rft-minter can conditionally write rft-codes and invoke Bedrock, nothing more. rft-attributor can read rft-clicks, write rft-referrals, and invoke rft-screen. rft-rewarder is the only role that can flip a referral, write rft-rewards, call the store reward API, publish to SNS, and invoke Bedrock — and it cannot delete from any table. rft-screen reads its inputs and sends via SES only. rft-sweep can query and update rft-referrals and has no inbound surface at all. Everything runs in eu-west-2; the only cross-Region path is Bedrock’s Global inference profile, which routes the model call for capacity and is not a data store. An AWS Budgets alarm watches the monthly spend — with a runaway loop (a webhook storm, a code being sprayed) the thing most likely to move it, a Budgets alert is the cheapest early warning that something is running hot, and it pairs with a CloudWatch alarm on the rft-jobs-dlq depth.

That’s the whole system: a redirect that logs a click, a queue that carries the rest, six small functions, five tables, and two conditional writes that make the money move exactly once. It turns a customer’s offhand recommendation into a link you can follow and a reward you can trust — and it does it for less than the price of the coffee the referrer and their friend might have had while they talked you up.

All posts