09. Architecture Decisions

This document captures the key architectural decisions made for this project using the Architecture Decision Record (ADR) format.

ADR-001: Use DynamoDB Single-Table Design

Status: Accepted

Context

The Subscription Platform requires a database to store and manage:

  • Merchants

  • Products

  • Orders

  • Subscriptions

The system must support:

  • Fast read and write operations

  • Low operational cost

  • Automatic scaling (serverless environment)

  • High availability with minimal infrastructure management

Traditional relational databases introduce operational overhead (connection pooling, scaling, maintenance), which conflicts with the serverless architecture goals.

Decision

We will use Amazon DynamoDB with a single-table design.

All entities (merchants, products, orders, subscriptions) will be stored in a single table using:

  • Partition Key (PK)

  • Sort Key (SK)

Access patterns will be modeled upfront to support efficient queries.

Rationale

  • Serverless scaling: On-demand capacity automatically scales with traffic

  • Cost efficiency: Pay-per-request model (scales to zero)

  • Performance: Single-digit millisecond latency

  • No connection management: Uses HTTP API instead of persistent DB connections

  • Operational simplicity: One table instead of multiple reduces complexity

  • Best fit for access-pattern-driven design

Consequences

✅ Positive

  • Highly scalable and resilient architecture

  • Simplified infrastructure management

  • Optimized for known access patterns

  • Reduced operational overhead

⚠️ Negative

  • Requires strict upfront data modeling

  • Queries are less flexible than SQL

  • Harder to perform ad-hoc queries

  • Team must learn DynamoDB single-table design patterns

Notes

This decision aligns with a serverless-first architecture and prioritizes:

  • scalability

  • performance

  • cost optimization

Future changes to access patterns may require schema evolution or additional indexes (GSIs).