← Week 1: Design & Architecture

Day 4: Data Model Design

Phase 7 · Sep 26, 2026

← Week 1: Design & Architecture

Agenda (2–3 hours)

  • Design (90 min): DynamoDB single-table schema for the task queue — all access patterns, GSIs, event store structure
  • Review (60 min): Verify every access pattern is served; calculate RCU/WCU for 500 tasks/second
  • Document (30 min): Record the table design as a reference artifact
← Week 1: Design & Architecture

Single-Table Schema

PK                  SK                      GSI1-PK          GSI1-SK
TASK#t-123          META                    STATUS#PENDING   CREATED#2026-09-23T10:00:00Z
TASK#t-123          EVENT#0001              -                -  (SUBMITTED)
TASK#t-123          EVENT#0002              -                -  (PROCESSING)
TASK#t-123          EVENT#0003              -                -  (COMPLETED)
IDEM#client-uuid    TASK#t-123              -                -  (idempotency map)
WORKER#w-abc        TASK#t-123              -                -  (current claim)
← Week 1: Design & Architecture

Access Patterns

Pattern Key condition Notes
Get task metadata PK=TASK#id, SK=META GetItem
Get task history PK=TASK#id, SK begins_with EVENT# Query, sorted by event sequence
List pending tasks GSI1: PK=STATUS#PENDING For admin UI; not the worker path
Check idempotency PK=IDEM#key, SK begins_with TASK# GetItem before SubmitTask
Claim task (atomic) UpdateItem on META with condition status=PENDING Returns old status for conflict detection
← Week 1: Design & Architecture

Capacity Calculation

At 500 tasks/second (submission path):

  • PutItem event (SUBMITTED): 1 WCU × 500 = 500 WCU/s
  • PutItem idempotency record: 1 WCU × 500 = 500 WCU/s
  • UpdateItem META (status): 1 WCU × 500 = 500 WCU/s

Total write: ~1,500 WCU/s → provision 2,000 WCU/s with auto-scaling

Processing path (500 tasks/second workers):

  • UpdateItem claim (conditional): 1 WCU × 500 = 500 WCU/s
  • PutItem PROCESSING event: 1 WCU × 500 = 500 WCU/s
  • PutItem COMPLETED event: 1 WCU × 500 = 500 WCU/s

Total: ~3,500 WCU/s peak → use on-demand capacity mode during development

← Week 1: Design & Architecture

Key Takeaways

  • Single-table design collocates task metadata and event history in one partition (fast reads)
  • Idempotency map is a separate item — GetItem before write, then PutItem with attribute_not_exists condition
  • Conditional update for task claim (status=PENDING) makes claiming atomic without transactions
  • On-demand capacity mode eliminates provisioning guesswork during development

Tomorrow: observability plan — what to instrument, what to measure, what to alert on.