Documentation Index
Fetch the complete documentation index at: https://www.aidonow.com/llms.txt
Use this file to discover all available pages before exploring further.
Executive Summary
Single-table DynamoDB design delivers measurable operational benefits—zero cross-tenant data leaks, sub-100ms hierarchical query performance, and substantial repository boilerplate reduction—when applied within bounded domain contexts. However, organizations that extend single-table design across entire application surfaces encounter escalating cost and engineering overhead, particularly for analytics, flexible search, and time-series workloads. A production deployment encompassing 56 entity types and 23,820 lines of DynamoDB code over 12 months revealed four critical anti-patterns that collectively introduced an estimated $55,440 in first-year costs, including technical debt and ongoing operational waste. The appropriate architectural posture is one table per bounded context, not one table per application. AI-assisted codebase auditing identified all four anti-patterns at a fraction of the cost of manual review.Key Findings
- Single-table design is context-scoped, not application-wide. Applying a single-table model across unbounded domains produces conflicting access patterns, GSI proliferation, and cross-domain compliance entanglement.
- Direct AWS SDK bypasses represent the highest-risk architectural violation. A production audit identified 217 direct SDK calls circumventing tenant isolation, PII encryption, audit logging, and retry logic—an estimated $24,000 remediation liability.
- DynamoDB is not cost-competitive for time-series workloads. Analytics data stored in DynamoDB cost 45 per month for an equivalent purpose-built time-series service—a 5.6× cost differential.
- GSI proliferation signals access-pattern misalignment. Entities requiring more than three GSIs to serve query requirements are systematically better served by a search platform; the observed 12-GSI proliferation cost an estimated 120 engineering hours.
- AI-assisted auditing identifies architectural violations at scale. A 23,820-line codebase was scanned in 15 minutes, producing actionable violation reports with file-level and line-level specificity.
- Technical debt in distributed data access patterns compounds without automated governance. Without preventive controls, the observed SDK violation rate is consistent with exponential growth in subsequent development periods.
1. Introduction: Scope and Methodology
Single-table DynamoDB design, as formalized and popularized through AWS re:Invent presentations and practitioner literature, posits that all entities within an application can be stored in a single DynamoDB table through disciplined use of composite keys and Global Secondary Indexes (GSIs). The model offers well-documented advantages: reduced operational overhead, predictable latency at scale, and co-located entity hierarchies. This analysis documents a 12-month production deployment of a multi-tenant SaaS platform using single-table DynamoDB, covering the full evolution from an initial single-table design to an architecture of 19 domain-aligned tables. The deployment comprised 56 entity types, 23,820 lines of DynamoDB-related code, and an AI-powered audit system that identified and quantified architectural violations across the codebase. The analytical objective is to derive a replicable decision framework for practitioners evaluating single-table DynamoDB design, grounded in production evidence rather than idealized demonstrations.2. Where Single-Table Design Delivers Value
2.1 Tenant Isolation via Partition Key Enforcement
The most consequential operational benefit of single-table DynamoDB for multi-tenant platforms is the enforcement of tenant data isolation at the database access layer, not the application logic layer. When the partition key schema uniformly encodes the tenant identifier—for example,TENANT#<tenant_id>—DynamoDB’s query semantics make cross-tenant access structurally impossible for well-formed queries.
The following repository pattern illustrates this isolation guarantee:
2.2 Hierarchical Query Performance
Single-table design provides a structural advantage for hierarchical entity relationships. Sort key prefix patterns enable multi-level parent-child traversal in a single query, eliminating join operations that relational databases require and that DynamoDB does not support natively. The following pattern demonstrates hierarchical traversal at sub-100ms latency:2.3 Macro-Driven Repository Automation
Single-table patterns exhibit high structural regularity within a bounded context, making them amenable to code generation through procedural macros. The platform implements a#[derive(DynamoRepository)] macro that generates the full repository layer from a declarative entity annotation:
2.4 Geographic Data Residency
Tenant-aligned partition keys provide a natural routing anchor for multi-region data residency compliance. The following pattern routes writes to the appropriate regional DynamoDB table based on tenant configuration:3. Anti-Patterns and Their Costs
3.1 Anti-Pattern: Direct AWS SDK Bypass
An AI audit of the production codebase identified 217 instances of directaws-sdk-dynamodb calls that bypassed the repository abstraction layer. Each such instance eliminated the protections that the repository layer enforces: tenant isolation validation, PII field encryption, audit event emission, and exponential backoff retry logic.
The following example illustrates the class of violation:
3.2 Anti-Pattern: Scan Operations in List Queries
Seven repositories were identified usingscan() operations instead of query() for standard list operations. DynamoDB scan() reads every item in the table before applying filter expressions; filter evaluation occurs after reads, providing no cost savings.
The following example demonstrates the problematic pattern and its resolution:
3.3 Anti-Pattern: Excessive GSI Proliferation
When entities require more than two or three GSIs to serve their access patterns, the cumulative cost of single-table design typically exceeds that of a purpose-built search service. The product catalog entity in this deployment required four GSIs:3.4 Anti-Pattern: Time-Series Data in DynamoDB
DynamoDB pricing is based on provisioned or consumed read/write capacity units, with costs scaling linearly with data volume. Purpose-built time-series databases optimize for compression, downsampling, and aggregation—capabilities that DynamoDB does not provide natively, requiring expensive application-layer computation. The original metrics repository:4. Comparative Analysis: Database Selection by Workload
The following table summarizes workload characteristics and the recommended persistence mechanism based on observed production outcomes.| Workload Type | Recommended Service | Rationale | DynamoDB Suitability |
|---|---|---|---|
| Transactional CRUD within bounded context | DynamoDB (single-table) | Tenant isolation, hierarchical queries, predictable latency | High |
| Hierarchical parent-child traversal | DynamoDB (single-table) | Sort key prefix enables no-join traversal | High |
| Full-text and flexible attribute search | OpenSearch | No GSI proliferation, flexible query composition | Low |
| Time-series with aggregation | AWS Timestream | Native compression, downsampling, SQL aggregation | Low |
| Cross-domain analytics joins | Redshift / Snowflake | Columnar storage, SQL joins across domains | Not applicable |
| Session/ephemeral data | DynamoDB (TTL) | Built-in TTL, low operational overhead | High |
| Audit logs (long-retention) | S3 + Athena | Cost-efficient cold storage, SQL query access | Moderate |
The recommended database selection principle is: use DynamoDB for transactional workloads with known, bounded access patterns; delegate analytics, search, and time-series workloads to purpose-built services. Cost modelling should be performed before committing to DynamoDB for any workload that requires aggregation, flexible filtering, or cross-entity joins.
5. Cost Summary
The following table quantifies the total first-year cost attributable to the four anti-patterns identified in this analysis.| Anti-Pattern | One-Time Remediation Cost | Monthly Recurring Waste | Annual Total |
|---|---|---|---|
| 217 direct SDK bypasses | 200/hr) | — | $24,000 |
| 7 scan operations | — | $210/month | $2,520 |
| 12 GSI over-provision | $20,000 opportunity cost | — | $20,000 |
| Time-series in DynamoDB | — | $210/month | $2,520 |
| Total | $44,000 | $420/month | $49,040 |
6. AI-Assisted Architectural Auditing
Manual review of a 23,820-line codebase for architectural violations is estimated at 120 senior-engineer-hours. An AI-assisted audit completed the equivalent analysis in approximately 15 minutes, producing findings with file-level and line-level specificity. The audit identified all 217 SDK violations, all seven scan operations, and all 12 GSI over-provisions with zero false negative architectural categories. AI auditing excels at pattern-matching violations against established rules across large codebases. Human judgment remains essential for validating findings, adjudicating edge cases, and making architectural trade-off decisions (for example, whether a specific GSI is justified given access frequency).7. Decision Framework: When to Apply Single-Table Design
7.1 Indicators for Single-Table DynamoDB
Organizations should apply single-table DynamoDB when the following conditions hold:- Entities share a domain boundary. The target entities participate in the same bounded context (for example, CRM entities: Lead, Account, Opportunity, Contact).
- Hierarchical access patterns dominate. The primary query model involves traversal of parent-child relationships within a tenant scope.
- Access patterns are known and stable. The required GSI set can be fully specified at design time and is not expected to grow beyond two to three indexes.
- Tenant isolation is a first-order requirement. The partition key schema enforces isolation by construction, eliminating reliance on application-layer guards.
7.2 Indicators Against Single-Table DynamoDB
Organizations should select an alternative persistence mechanism when any of the following conditions hold:- Cross-domain queries are required. DynamoDB does not support joins; cross-domain analytics require a data warehouse or OLAP database.
- Access patterns are unpredictable or evolving. Each new access pattern requires a new GSI; storage costs multiply as GSI count grows.
- Time-series aggregation is a primary workload. Purpose-built services provide native compression and aggregation at substantially lower cost.
- Different entities require different retention policies. Audit logs requiring seven-year retention should not co-exist in the same table as session data with 24-hour TTL.
8. Recommendations
-
Define and enforce a repository abstraction layer before writing any DynamoDB access code. Pre-commit hooks should reject any direct
aws-sdk-dynamodbcalls outside the designated repository module. Enforcement prior to development eliminates the remediation liability documented in Section 3.1. - Establish a GSI count threshold as an architectural fitness function. Entities requiring more than three GSIs should be evaluated for migration to OpenSearch before implementation proceeds. This threshold should be integrated into code review checklists and automated linting rules.
- Conduct a workload classification exercise before selecting DynamoDB. For each planned entity type, explicitly classify the workload as transactional, time-series, full-text search, or analytical. Only transactional workloads with known access patterns should be assigned to DynamoDB.
- Implement AI-assisted quarterly architectural audits. Define a machine-readable violation ruleset and run automated scans against the production codebase. The cost differential between proactive auditing and reactive remediation is approximately 10:1 based on the evidence in this analysis.
- Use multi-region data residency routing at the repository layer. Geographic data residency for regulatory compliance is most reliably achieved by routing writes through region-aware repository constructors rather than application-layer conditional logic.
- Migrate time-series workloads to purpose-built services at project inception. The 5.6× monthly cost differential identified in Section 3.4 is compounded by the application-layer aggregation overhead that DynamoDB necessitates. Early migration avoids both the cost differential and the engineering debt of custom aggregation logic.
9. Conclusion
The single-table DynamoDB model is a well-validated architectural pattern for transactional, tenant-isolated, hierarchically structured data within bounded domain contexts. Its application to entire application surfaces—spanning analytics, flexible search, and time-series workloads—introduces avoidable costs and operational complexity. Production evidence from a 12-month deployment establishes that the appropriate unit of single-table design is the bounded context, not the application. The four anti-patterns identified in this analysis—SDK layer bypass, scan-based list operations, GSI proliferation, and time-series data in DynamoDB—are systematic rather than incidental. They are predictable outcomes of applying single-table design beyond its zone of competence and of developing without enforced architectural constraints. Organizations that instrument preventive governance mechanisms before scaling will avoid the remediation liabilities documented here. As AI-assisted development tooling matures, the capacity for continuous architectural auditing at the codebase level will increasingly serve as a cost-effective substitute for periodic manual review. The combination of AI-driven violation detection and human architectural judgment represents a governance model well-suited to the pace and scale of modern software delivery.Resources
- AWS re:Invent: Advanced DynamoDB Design Patterns (Rick Houlihan)
- DynamoDB Best Practices
- The DynamoDB Book by Alex DeBrie
- Why We Moved From DynamoDB to Timestream (Corey Quinn)
- The Macro That Wrote 80% of Our Repositories (this blog)
Further reading: The Macro That Wrote 80% of Our Repositories — How Rust macros automated the repository layer boilerplate that single-table design demands.
All content represents personal learning from personal projects. Code examples are sanitized and generalized. No proprietary information is shared. Opinions are my own and do not reflect my employer’s views.