DEV Community: Heartlin Machado

Sharding Hot Partitions in DynamoDB: Why Your Single-Partition Log Table Will Break at Scale

Heartlin Machado — Thu, 25 Jun 2026 04:53:45 +0000

This post was created for the H0: Hack the Zero Stack hackathon. #H0Hackathon

I shipped a DynamoDB table with a hot partition and didn't notice for three weeks. At demo scale (700 items, a few writes per minute) everything worked. It would have been fine right up until it wasn't.

The anti-pattern was obvious in hindsight: every AI operation log entry was written to PK: "OPS_LOG". A single partition key for an append-only, high-throughput write stream. This is the exact workload that hits DynamoDB's per-partition throughput ceiling.

Here's what I found, why it matters, and the three patterns I used to fix it, all without a table migration.

The problem: per-partition throughput limits

DynamoDB scales horizontally by splitting data across partitions. Each partition handles:

3,000 RCU (read capacity units) for eventually consistent reads
1,000 WCU (write capacity units)
10 GB of data

When you use PAY_PER_REQUEST (on-demand) billing mode, DynamoDB auto-scales table-level capacity. But it doesn't auto-scale within a partition. If all your writes hit the same partition key, you're bottlenecked at 1,000 WCU on that one partition regardless of your table-level throughput.

A note on adaptive capacity: DynamoDB does have an adaptive capacity feature that can temporarily boost a hot partition's throughput by borrowing from underutilized partitions. But adaptive capacity is a safety net, not a design strategy. It activates reactively, has limits, and doesn't eliminate the per-partition ceiling. Designing around the constraint is always better than relying on the database to compensate for a bad access pattern.

For PK: "OPS_LOG", with every single AI operation landing on one partition key, this means:

At 1 write/second: no problem
At 100 writes/second: no problem
At 1,001 writes/second: throttled. ProvisionedThroughputExceededException.

A real anti-counterfeiting platform processing scans across thousands of brands could easily hit this. And the failure mode is silent at first: DynamoDB retries internally with exponential backoff. You only see it as increased latency, then as dropped writes.

Where I found hot partitions

I audited every PK pattern in my single-table design and found three hot spots. The simplest detection method: count the cardinality of each PK pattern. If a PK has cardinality of 1 (every write goes to the same key), it's a hot partition by definition.

1. OPS_LOG (AI operations telemetry)

// BEFORE: Every AI call writes to the same PK
{
  PK: "OPS_LOG",
  SK: "2026-06-22T01:00:00Z#threat_detector",
  agent: "threat_detector",
  latencyMs: 340,
  aiSeverity: "HIGH",
  ...
}

Problem: Unbounded write concentration. Every AI classification, regardless of brand, product, or time, lands on one partition key. PK cardinality: 1.

2. THREAT#brandId (threat alerts)

// BEFORE: All threats for one brand in one partition
{
  PK: "THREAT#brand-abc-123",
  SK: "ALERT#2026-06-22T01:00:00Z#geographic_anomaly",
  severity: "HIGH",
  ...
}

Problem: A brand under active counterfeiting attack generates hundreds of alerts per day. All writes concentrate on THREAT#brand-abc-123. The brand being attacked the hardest gets the worst write performance. Exactly backwards from what you want.

3. BRAND_INDEX / PRODUCT_INDEX (collection keys)

// Collection key for "list all brands" without Scan
{
  PK: "BRAND_INDEX",
  SK: "BRAND#2026-06-22T01:00:00Z#abc",
  name: "Luxe Watches",
  ...
}

Problem: If brand registrations spike (product launch, marketing campaign), all writes hit BRAND_INDEX. Same issue as OPS_LOG. PK cardinality: 1.

The fix: three sharding patterns

Pattern 1: Time-bucketed sharding (for OPS_LOG)

Instead of a single OPS_LOG key, bucket writes by date:

// AFTER: Daily-bucketed partition keys
const dateBucket = timestamp.slice(0, 10); // "2026-06-22"
{
  PK: `OPS_LOG#${dateBucket}`,       // OPS_LOG#2026-06-22
  SK: `${timestamp}#${agent}`,
  GSI1PK: "OPS_LOG",                  // For cross-day queries
  GSI1SK: timestamp,
  ...
}

Write path: Each day's ops entries go to a different partition. Today's 1,000 writes go to OPS_LOG#2026-06-22. Tomorrow's go to OPS_LOG#2026-06-23. The per-partition WCU limit applies per day, not per all-time. PK cardinality goes from 1 to 365/year.

Read path: The dashboard needs recent ops entries across days. Two options:

Option A: Scatter-gather

// Query each daily partition in parallel
const days = 7;
const buckets = [];
for (let i = 0; i < days; i++) {
  const d = new Date(Date.now() - i * 86400000);
  buckets.push(d.toISOString().slice(0, 10));
}

const results = await Promise.all(
  buckets.map(date =>
    queryItems(`OPS_LOG#${date}`, undefined, { limit: 50, scanForward: false })
  )
);

// Merge and sort
const logs = results.flat()
  .sort((a, b) => b.timestamp.localeCompare(a.timestamp))
  .slice(0, limit);

7 parallel queries, each hitting a different partition. DynamoDB handles them concurrently. Total latency is the slowest single query, typically under 20ms.

Option B: GSI1 query

// Single query across all days via GSI
const logs = await queryGSI1("OPS_LOG", undefined, { limit: 50, scanForward: false });

The GSI1 projection has GSI1PK: "OPS_LOG" across all daily partitions. This re-concentrates reads on one GSI partition key, but reads are less critical than writes (3,000 RCU vs 1,000 WCU limit), and the dashboard is low-frequency.

I use scatter-gather as the primary path and GSI1 as a fallback.

Pattern 2: Month-bucketed sharding (for THREAT)

Threats are read by brand, so the bucket needs to include the brand ID:

// AFTER: Monthly-bucketed by brand
const monthBucket = timestamp.slice(0, 7); // "2026-06"
{
  PK: `THREAT#${brandId}#${monthBucket}`,   // THREAT#abc#2026-06
  SK: `ALERT#${timestamp}#${type}`,
  GSI1PK: `BRAND#${brandId}`,               // Cross-month queries
  GSI1SK: `THREAT#${timestamp}`,
  ...
}

Why monthly, not daily? Threats are lower volume than ops logs. A busy brand might get 10-50 threats per day. Monthly bucketing is sufficient to prevent hot-spotting while keeping the scatter-gather read path manageable (query last 3 months = 3 parallel queries vs 90 for daily).

Read path: GSI1 query on BRAND#brandId with SK prefix THREAT# returns threats across all monthly buckets, sorted by timestamp, no scatter-gather needed:

const threats = await queryGSI1(`BRAND#${brandId}`, "THREAT#", {
  limit: 50,
  scanForward: false,
});

This is the ideal pattern: shard writes on the base table, unify reads on a GSI.

Pattern 3: Accept the trade-off (for collection keys)

BRAND_INDEX and PRODUCT_INDEX are also single-partition keys. But brand and product registration is low-throughput: maybe 50 per day during a hackathon, maybe 500 per day in production. The 1,000 WCU per-partition limit won't be hit.

The decision: Don't shard collection keys. The engineering cost of scatter-gather reads on "list all brands" isn't justified when registration throughput will never approach the partition limit.

If it did (say, an enterprise customer bulk-importing 10,000 products via the batch endpoint), I'd switch to PRODUCT_INDEX#<shard> with N-way random sharding:

const shard = Math.floor(Math.random() * 10);
{
  PK: `PRODUCT_INDEX#${shard}`,  // Random distribution across 10 partitions
  SK: `PRODUCT#${timestamp}#${id}`,
  ...
}

Read path: scatter-gather across shards 0-9, merge, sort. But I don't need this today. YAGNI applies to partition sharding too.

How to detect hot partitions

1. Count your PK cardinality

The simplest check, no monitoring required. Read every PutItem and UpdateCommand in your codebase. For each one, ask:

Is this PK cardinality bounded or unbounded? PRODUCT#uuid = unbounded (good). OPS_LOG = bounded to 1 (bad).
Does this PK receive burst traffic? A PK that gets 1 write/hour is fine even if it's singleton. A PK that gets 1,000 writes/second needs sharding.
What's the growth rate? A PK with 100 items forever is different from a PK that grows by 1,000 items/day.

2. CloudWatch Contributor Insights

Enable Contributor Insights on the table. It shows the top-N partition keys by consumed capacity. If one PK is 80% of your write traffic, you have a hot partition even if you're not throttled yet. ThrottledRequests per table only fires after you're already impacted. Contributor Insights catches the problem before it hurts.

3. Write a risk matrix

Document every write operation with its PK. If you see the same PK in multiple write paths, that's a convergence signal:

Write Operation	PK	Risk
Register brand	`BRAND#uuid`	Low: unique per brand
Register product	`PRODUCT#uuid`	Low: unique per product
Record scan	`PRODUCT#uuid`	Medium: popular products get many scans
Write threat	`THREAT#brand#month`	Low: monthly bucketing distributes
Write ops log	`OPS_LOG#date`	Low: daily bucketing distributes
Brand index	`BRAND_INDEX`	Low: registration is low-throughput

If the Risk column says "High" for anything, shard it.

Summary: the three decisions

Hot Partition	Pattern	Bucket Size	Read Strategy
OPS_LOG	Time-bucketed	Daily	Scatter-gather (7 parallel queries)
THREAT#brand	Time-bucketed	Monthly	GSI1 query (single partition)
BRAND_INDEX	Accepted	N/A	Single partition query

The fix for OPS_LOG was 8 lines in the Lambda writer and 15 lines in the API reader. No table migration. No GSI rebuild. No downtime. The monthly THREAT bucketing was similarly surgical: change the PK format in the Lambda and switch the reader to GSI1.

That's the beauty of DynamoDB's schemaless design: you can change your partition key format mid-stream without touching existing data. New writes go to the new pattern; old data stays readable through legacy fallback queries. You don't need a migration. You need a new PutItem and a Query that checks both patterns.

The code

All changes are in a single commit: refactor: shard hot partitions, eliminate Scans, document access patterns.

Key files:

lambda/threat-detector.mjs: OPS_LOG daily bucketing and THREAT monthly bucketing
src/app/api/ops-log/route.ts: scatter-gather read across daily buckets
src/app/api/threats/route.ts: GSI1 read across monthly buckets
src/lib/dynamodb.ts: updated schema documentation

Built for the H0: Hack the Zero Stack hackathon using DynamoDB and Vercel. #H0Hackathon

DynamoDB Streams and Lambda for Real-Time Threat Detection: The Event Pipeline DynamoDB Was Built For

Heartlin Machado — Thu, 25 Jun 2026 04:47:09 +0000

This post was created for the H0: Hack the Zero Stack hackathon. #H0Hackathon

A consumer scans a product's QR code. Five seconds later, a threat alert appears on the brand's dashboard, no page refresh, no polling. The entire pipeline is DynamoDB Streams firing a Lambda, writing a threat alert back to DynamoDB, and pushing it to the browser via Server-Sent Events.

This post walks through the complete pipeline I built for GenuProof, an anti-counterfeiting platform running on DynamoDB and Vercel. Every component is serverless. Cost at zero traffic: $0.

The architecture

Consumer scans QR > Vercel API Route > DynamoDB PutItem (SCAN# record)
                                              |
                                              v
                                    DynamoDB Stream (NEW_IMAGE)
                                              |
                                              v
                                    Lambda: authentik-threat-detector
                                      |-- Geographic anomaly check
                                      |-- Burst scan detection
                                      |-- Claim violation check
                                      |-- Hash tampering check
                                              |
                                         (if anomaly)
                                              |
                                              v
                                    DynamoDB PutItem (THREAT# alert)
                                              |
                                              v
                                    SSE endpoint polls THREAT#
                                              |
                                              v
                                    Brand dashboard updates (no refresh)

Step 1: The scan write triggers the Stream

When a consumer verifies a product, the Vercel API route writes a scan record:

const scanRecord = {
  PK: `PRODUCT#${productId}`,
  SK: `SCAN#${new Date().toISOString()}`,
  productId,
  timestamp: now,
  ip,
  country: geo.country,
  city: geo.city,
  userAgent: req.headers.get("user-agent"),
  result: hashMatch && signatureValid ? "authentic" : "suspicious",
};
await putItem(scanRecord);

This write hits DynamoDB. Because Streams is enabled with NEW_IMAGE view type, DynamoDB emits a stream record containing the complete new item. The stream record goes to a shard, and our Lambda function is subscribed to that shard.

Step 2: Lambda receives the stream event

The Lambda function is configured as a DynamoDB Stream trigger:

Batch size: 10 (process up to 10 records per invocation)
Batching window: 5 seconds (wait up to 5s to fill the batch)
Starting position: LATEST

export async function handler(event) {
  for (const record of event.Records) {
    if (record.eventName !== "INSERT") continue;

    const newImage = record.dynamodb.NewImage;
    const sk = newImage.SK.S;

    // Only process scan records and provenance events
    if (sk.startsWith("SCAN#")) {
      await processScan(newImage);
    } else if (sk.startsWith("EVENT#")) {
      await processEvent(newImage);
    }
  }
}

Key detail: the Lambda filters by SK prefix. Because this is a single-table design, the Stream contains writes for all entity types: brand profiles, product registrations, webhook configs. The Lambda ignores everything except SCAN# and EVENT# records. This filtering happens in application code, not at the Stream level, which means we pay for Lambda invocations on non-scan writes. At our scale, this is negligible. At very high write volume, you'd use DynamoDB Stream event filtering to filter at the infrastructure level.

Step 3: Anomaly detection (four checks)

For each scan record, the Lambda runs four sequential anomaly checks:

Geographic anomaly

// Query recent scans for this product (last 24 hours)
const recentScans = await ddb.send(new QueryCommand({
  TableName: TABLE,
  KeyConditionExpression: "PK = :pk AND SK BETWEEN :start AND :end",
  ExpressionAttributeValues: {
    ":pk": `PRODUCT#${productId}`,
    ":start": `SCAN#${twentyFourHoursAgo}`,
    ":end": `SCAN#${now}`,
  },
}));

const countries = new Set(recentScans.Items.map(s => s.country.S));
if (countries.size >= 3) {
  // Same product scanned from 3 or more countries in 24h
  anomalyType = "geographic_anomaly";
}

This is the pattern DynamoDB was built for: range query within a partition, sorted by timestamp. The SK SCAN#2026-06-22T01:00:00Z sorts lexicographically as a timestamp. The BETWEEN query returns only scans in the 24-hour window, no filter expression needed, no wasted read capacity.

An important subtlety: DynamoDB Streams delivers records in order within a shard. This ordering guarantee is what makes burst detection correct. If scans arrived out of order, we couldn't reliably count "10 scans in the last hour" because the window would be inconsistent. Streams' per-shard ordering means the Lambda always sees scans in the sequence they were written.

Burst scan detection

const oneHourAgo = new Date(Date.now() - 3600000).toISOString();
const recentHourScans = recentScans.Items.filter(
  s => s.timestamp.S > oneHourAgo
);
if (recentHourScans.length >= 10) {
  anomalyType = "burst_scan";
}

Ten or more scans of the same product in one hour suggests someone is testing a cloned QR code, trying different devices and locations to see if the system catches them.

Claim violation

const claim = await ddb.send(new GetCommand({
  TableName: TABLE,
  Key: { PK: `PRODUCT#${productId}`, SK: "CLAIM" },
}));
if (claim.Item) {
  // Product already claimed by a consumer, new scan from different device
  anomalyType = "claimed_product_scan";
}

This is a GetItem: one partition read, one RCU. The CLAIM record was written when the original consumer claimed the product. Any subsequent scan from a different device fingerprint is suspicious.

Hash tampering

if (verificationResult !== "authentic") {
  anomalyType = "hash_tampering";
}

If the scan record itself shows the product failed hash verification, something is fundamentally wrong: either the database was tampered with or the product record was modified. CRITICAL severity.

Step 4: Write the threat alert

If any check fires, the Lambda writes a threat alert back to DynamoDB:

const monthBucket = timestamp.slice(0, 7); // "2026-06"
const alert = {
  PK: `THREAT#${brandId}#${monthBucket}`,
  SK: `ALERT#${timestamp}#${type}`,
  GSI1PK: `BRAND#${brandId}`,
  GSI1SK: `THREAT#${timestamp}`,
  brandId, type, severity, productId, details, timestamp,
  resolved: false,
  source: "lambda-stream",
};
await ddb.send(new PutCommand({ TableName: TABLE, Item: alert }));

Note the monthly-bucketed PK: THREAT#brandId#2026-06. If we used THREAT#brandId as a flat PK, a brand that generates thousands of threat alerts would create a write-hot partition, all writes concentrating on one partition key. Monthly bucketing distributes writes across time-based partitions. (I wrote a separate post on sharding hot partitions if you want the full breakdown.)

The GSI1PK: "BRAND#brandId" projection means we can query all threats for a brand across monthly buckets with a single GSI1 query, no scatter-gather needed on the read path.

Step 5: SSE pushes to the dashboard

The final piece: getting the alert to the brand's browser without polling from the client side.

The Vercel API has an SSE (Server-Sent Events) endpoint that the dashboard connects to:

// Client (React component)
const source = new EventSource(`/api/stream?brandId=${brandId}`);
source.addEventListener("threat", (e) => {
  const threat = JSON.parse(e.data);
  setThreats(prev => [threat, ...prev]);
});

The server-side SSE endpoint queries DynamoDB every 3 seconds for new threats newer than the last timestamp:

const threats = await queryGSI1(`BRAND#${brandId}`, `THREAT#${lastTimestamp}`, {
  limit: 10,
  scanForward: true,
});
for (const threat of threats) {
  controller.enqueue(encoder.encode(`event: threat\ndata: ${JSON.stringify(threat)}\n\n`));
  lastTimestamp = threat.timestamp;
}

The total latency from scan-to-dashboard:

PutItem scan record: ~5ms
Stream delivery to Lambda: ~100-500ms
Lambda anomaly checks: ~50-200ms (includes DynamoDB queries)
PutItem threat alert: ~5ms
SSE poll interval: up to 3s

Total: under 5 seconds from QR scan to dashboard alert.

Error handling and retry guarantees

What happens when the Lambda fails mid-execution? DynamoDB Streams has built-in retry:

At-least-once delivery: if the Lambda throws, DynamoDB retries the same batch. The function must be idempotent (writing a threat alert with the same PK/SK is a no-op PutItem, naturally idempotent).
Ordering preserved on retry: retries deliver the same records in the same order within the shard. Your anomaly detection logic sees a consistent sequence regardless of how many retries occurred.
Bisect on error: if a batch consistently fails, DynamoDB splits it in half and retries each half separately, isolating the poisoned record.

The Lambda doesn't need a dead-letter queue at our scale. If a record genuinely can't be processed after retries, it ages out of the 24-hour Stream retention window. No scan goes unprocessed silently: the scan record itself is already in DynamoDB, and the anomaly detection runs again on the next scan for the same product.

Why DynamoDB Streams (not SQS, not EventBridge)

The alternative architecture would be: write to DynamoDB, then separately publish to SQS or EventBridge, then subscribe a Lambda, then write the alert back. That's three services instead of one.

DynamoDB Streams collapses the first two into a built-in feature. The advantages over a separate message bus:

Zero infrastructure: no queue to create, no dead-letter queue to configure, no IAM policies for cross-service access
Guaranteed delivery: every successful DynamoDB write generates a stream record. No "forgot to publish" bugs.
Ordered processing: records arrive in write order within a shard. SQS standard queues don't guarantee ordering. SQS FIFO queues do, but require explicit deduplication IDs.
Same-table writes: the Lambda reads from DynamoDB and writes back to the same table. One set of credentials, one IAM policy, one table.
Cost: $0 at rest. No base cost when nobody is scanning. Lambda charges only for invocations.

The Lambda function

The full Lambda is 412 lines. Here's what each section does:

Lines	Function	Purpose
1-20	Setup	DynamoDB client, env vars, table name
21-40	handler()	Stream record iteration, SK filtering
41-106	anomalyChecks()	Four detection checks
108-250	processScan()	Orchestrates checks and writes
252-355	AI integration	Classification (downstream consumer of the pipeline)
356-397	writeAlert()	Threat alert with monthly bucketing
400-412	writeOpsLog()	Telemetry with daily bucketing

The complete source is in lambda/threat-detector.mjs at github.com/4KInc/genuproof.

Stream configuration

Setting	Value	Why
View type	NEW_IMAGE	Need the full item to run anomaly checks
Batch size	10	Process multiple scans per invocation to reduce Lambda cold starts
Batching window	5 seconds	Allows batching during burst periods
Starting position	LATEST	Only process new writes, not historical data
Retry	2	Retry failed batches (Streams guarantees ordering within retry)

What I learned

Single-table design with Streams is the canonical DynamoDB architecture. One table gives you one Stream. One Stream gives you one event pipeline. The simplicity is the point.
Filter in application code, not infrastructure (at small scale). At large scale, use Lambda event source filtering to avoid paying for irrelevant invocations.
Monthly-bucketed threat partitions were a late addition after I realized the flat THREAT#brandId PK would hot-spot. The fix took 30 minutes and required zero table migration: change the PK format in the Lambda writer and switch the reader to GSI1.
SSE is underrated for real-time features. It's simpler than WebSockets, works through CDNs, and the 3-second poll against DynamoDB costs essentially nothing at demo scale.
Streams ordering enables correctness, not just convenience. Burst detection, geographic anomaly windows, and claim violation checks all depend on seeing scans in the order they were written. Without Streams' per-shard ordering guarantee, you'd need application-level sequencing.

Built for the H0: Hack the Zero Stack hackathon using DynamoDB and Vercel. #H0Hackathon

17 Access Patterns, Zero Scans, One DynamoDB Table: Single-Table Design for a 37-Endpoint SaaS

Heartlin Machado — Thu, 25 Jun 2026 04:44:57 +0000

This post was created for the H0: Hack the Zero Stack hackathon. #H0Hackathon

Single-table DynamoDB design sounds great until you have five entity types that all need to be listed, queried by different owners, and processed by a single event stream. That's where the tutorials stop and the real design work starts.

I'm building GenuProof, a B2B anti-counterfeiting platform on DynamoDB and Vercel. One table, 13 PK/SK patterns, 17 access patterns serving 37 API endpoints. Zero joins, zero full-table Scans on data paths, predictable cost at any scale. This post walks through every design decision.

Why single-table?

The alternative is one table per entity: brands, products, events, scans, threats, webhooks. In DynamoDB, that means six tables, six sets of capacity settings, six sets of alarms, and no way to fetch related data in a single query without application-level joins.

Single-table design puts everything in one table with composite primary keys. You get:

One capacity config to manage (PAY_PER_REQUEST in my case)
One DynamoDB Stream that captures every write across all entity types
Transactional writes across entities (same table = same TransactWriteItems call)
Simpler operations: one table to back up, monitor, and alarm on

The cost is upfront design work. You must know your access patterns before you write a line of code.

The access patterns

I started by listing every operation my 37 API endpoints need. Multiple endpoints share the same underlying access pattern (e.g., three different product-listing endpoints all use the same GSI1 query), which is why 37 endpoints collapse to 17 distinct patterns:

Access Pattern	Operation
Register a brand	PutItem
Get brand profile	GetItem
List all brands	Query
Get brand stats	GetItem
Register a product (with hash and signature)	PutItem (x5 items)
Verify a product by code	GetItem, GetItem, Query
List products by brand	Query (GSI1)
List all products for public gallery	Query
Add provenance event	PutItem
Get provenance chain	Query
Record verification scan	PutItem
Get scan history	Query
Write threat alert	PutItem
Get threats by brand	Query (GSI1)
Write AI operations log	PutItem
Read AI ops log (last 7 days)	Query (scatter-gather)
Consumer claim product	PutItem
Health check	Scan (Limit: 1)

That last one is the only Scan in the entire application, and it reads exactly one item to test DynamoDB connectivity.

The schema

Here are the 13 PK/SK patterns that serve those 37 endpoints:

PK                               SK                          Entity
────────────────────────────────────────────────────────────────────
BRAND#<id>                       PROFILE                     Brand profile
BRAND#<id>                       STATS                       Counters (atomic)
BRAND#<id>                       WEBHOOK#<id>                Webhook config
PRODUCT#<id>                     META                        Product record
PRODUCT#<id>                     EVENT#<ts>#<type>           Provenance event
PRODUCT#<id>                     SCAN#<ts>                   Scan log
PRODUCT#<id>                     CLAIM                       Consumer lock (TTL)
VERIFY#<code>                    META                        Code to product
HASH#<sha256>                    META                        Hash to product
THREAT#<brand>#<YYYY-MM>         ALERT#<ts>#<type>           Threat alert
OPS_LOG#<YYYY-MM-DD>             <ts>#<agent>                AI ops log
BRAND_INDEX                      BRAND#<ts>#<id>             Brand listing
PRODUCT_INDEX                    PRODUCT#<ts>#<id>           Product listing

And one GSI (GSI1):

GSI1PK                           GSI1SK                      Access Pattern
────────────────────────────────────────────────────────────────────
BRAND#<id>                       PRODUCT#<ts>                Products by brand
BRAND#<id>                       THREAT#<ts>                 Threats by brand
VERIFY#<code>                    META                        Code lookup
OPS_LOG                          <ts>                        Ops across days

CLAIM records carry a TTL attribute so expired consumer locks are automatically cleaned up by DynamoDB, keeping the per-product item collection lean and avoiding stale claim checks on products that were never disputed.

Key design decisions

1. Collection keys replace Scans

The most common DynamoDB anti-pattern in tutorials: "just Scan the table and filter." At 1,000 items, nobody notices. At 1,000,000, your Lambda times out and your bill spikes.

I needed "list all brands" and "list all products" without Scan. The solution: collection keys. When I register a brand, I write two items:

// The brand itself
{ PK: "BRAND#abc", SK: "PROFILE", name: "Luxe Watches", ... }

// The collection entry
{ PK: "BRAND_INDEX", SK: "BRAND#2026-06-22T01:00:00Z#abc", name: "Luxe Watches", ... }

Now "list all brands" is Query(PK = "BRAND_INDEX", ScanIndexForward = false), returning brands sorted by registration date, no Scan, O(n) on the result set.

Same pattern for products with PRODUCT_INDEX.

Trade-off: every registration writes one extra item. At DynamoDB's $1.25/million writes, this costs $0.00000125 per registration. Acceptable.

2. Verification in three hops (no joins)

The critical hot path: a consumer scans a QR code. The server must verify the product in under 100ms.

Step 1: GetItem(PK="VERIFY#wfPHybaFV3_a", SK="META")
        returns { productId: "e084..." }

Step 2: GetItem(PK="PRODUCT#e084...", SK="META")
        returns { hash, signature, name, brandId, ... }

Step 3: Query(PK="PRODUCT#e084...", SK begins_with "EVENT#")
        returns provenance chain, sorted by timestamp

Three DynamoDB operations, all on the same partition for steps 2-3. No joins, no Scans. DynamoDB returns each in single-digit milliseconds.

3. Atomic counters avoid read-modify-write

Brand statistics (product count, scan count, threat count) use DynamoDB's UpdateExpression with ADD:

await ddb.send(new UpdateCommand({
  TableName: TABLE,
  Key: { PK: `BRAND#${brandId}`, SK: "STATS" },
  UpdateExpression: "SET scanCount = if_not_exists(scanCount, :zero) + :one",
  ExpressionAttributeValues: { ":zero": 0, ":one": 1 },
}));

No read-before-write. No race condition. Works correctly under concurrent Lambda invocations.

4. GSI1 for cross-partition queries

Within a single partition, DynamoDB sorts by SK automatically. But "all products for brand X" and "all threats for brand X" live in different partitions (PRODUCT#id and THREAT#brand#month).

GSI1 solves this. Every product and threat writes GSI1PK: "BRAND#brandId" with a typed sort key. One GSI, two access patterns:

// Products by brand
Query(IndexName="GSI1", GSI1PK="BRAND#abc", GSI1SK begins_with "PRODUCT#")

// Threats by brand (across all monthly buckets)
Query(IndexName="GSI1", GSI1PK="BRAND#abc", GSI1SK begins_with "THREAT#")

5. One Stream feeds the entire event pipeline

Because everything is in one table, one DynamoDB Stream captures every write. The Lambda function filters by SK prefix:

for (const record of event.Records) {
  const sk = record.dynamodb.NewImage.SK.S;
  if (sk.startsWith("SCAN#")) { /* anomaly detection */ }
  if (sk.startsWith("EVENT#")) { /* chain gap analysis */ }
}

With multiple tables, you'd need multiple Streams and multiple Lambda functions. Single table means single stream means single pipeline. This is what makes the AI threat detection layer possible: the Lambda receives every scan, event, and product registration through a single stream, with no polling and no external message queue.

The numbers

1 table, PAY_PER_REQUEST
13 PK/SK patterns serving 37 API endpoints
1 GSI (GSI1) serving 4 cross-partition query patterns
0 Scans on data paths (only health probe: Limit 1)
696 items, 259 KB at demo scale
Sub-10ms single-item reads, sub-50ms queries

What I'd do differently

If I were starting over, I'd add a GSI2 for entity-type queries (GSI2PK = "PRODUCT", GSI2SK = createdAt) instead of collection keys. GSI2 would be automatically maintained by DynamoDB, no extra writes at registration time. I chose collection keys because they work without a table migration, and I was mid-hackathon.

Full access pattern matrix

Here's the complete matrix. 17 access patterns, zero Scans:

Access Pattern	PK	SK	Index	Scan?
Register brand	`BRAND#id` / `BRAND_INDEX`	`PROFILE` / `BRAND#ts`	Table	No
Get brand	`BRAND#id`	`PROFILE`	Table	No
List brands	`BRAND_INDEX`	`begins_with(BRAND#)`	Table	No
Brand stats	`BRAND#id`	`STATS`	Table	No
Register product	`PRODUCT#id` / `VERIFY#code` / `HASH#` / `PRODUCT_INDEX`	Multiple	Table	No
Verify product	`VERIFY#code` then `PRODUCT#id`	`META` then `EVENT#`	Table	No
Products by brand	`BRAND#id`	`begins_with(PRODUCT#)`	GSI1	No
Explore products	`PRODUCT_INDEX`	`begins_with(PRODUCT#)`	Table	No
Add event	`PRODUCT#id`	`EVENT#ts#type`	Table	No
Get chain	`PRODUCT#id`	`begins_with(EVENT#)`	Table	No
Record scan	`PRODUCT#id`	`SCAN#ts`	Table	No
Scan history	`PRODUCT#id`	`begins_with(SCAN#)`	Table	No
Write threat	`THREAT#brand#month`	`ALERT#ts`	Table	No
Get threats	`BRAND#id`	`begins_with(THREAT#)`	GSI1	No
Write ops log	`OPS_LOG#date`	`ts#agent`	Table	No
Read ops log	`OPS_LOG#date` x N	scatter-gather	Table	No
Health check	n/a	n/a	Table	Limit:1

The complete source is at github.com/4KInc/genuproof. The schema lives in src/lib/dynamodb.ts and the Lambda in lambda/threat-detector.mjs.

Built for the H0: Hack the Zero Stack hackathon using DynamoDB and Vercel. #H0Hackathon