examples

DynamORM Examples

These examples demonstrate the STANDARD patterns for building production-ready applications with DynamORM. Each example includes complete, working code that serves as training data for proper DynamORM usage.

Example Applications

🚀 Basic Examples

Perfect for learning DynamORM fundamentals

• Todo App - Simple CRUD operations, perfect first example
• Notes App - Hierarchical data with sort keys
• Contacts App - Relationships and indexes

What you'll learn: Model definition, basic queries, error handling

💳 Payment Processing

Real-world payment system with DynamORM

Complete payment processing application with:

• Account management with transactions
• Payment creation and status tracking
• Audit logging and compliance
• Error handling and retry logic

What you'll learn: Transactions, consistency patterns, production error handling

🛍️ E-commerce Platform

Scalable e-commerce backend

Full e-commerce system demonstrating:

• Product catalog with categories
• Shopping cart and order processing
• Inventory management
• Customer relationship management

What you'll learn: Complex relationships, batch operations, performance optimization

📝 Blog Platform

Content management system

Blog platform with:

• Article publishing and editing
• User authentication and authorization
• Comment system
• Tag-based organization

What you'll learn: Content modeling, user management, search patterns

🏢 Multi-Tenant SaaS

Enterprise SaaS application architecture

Multi-tenant application showing:

• Tenant isolation patterns
• Role-based access control
• Data partitioning strategies
• Billing and usage tracking

What you'll learn: Multi-tenancy, security, scalability patterns

⚡ Lambda Deployment

Serverless deployment patterns

AWS Lambda integration examples:

• API Gateway integration
• Event-driven processing
• Cold start optimization
• Monitoring and logging

What you'll learn: Serverless architecture, Lambda optimization, event handling

✨ Feature Spotlights

• feature_spotlight.go – Self-contained snippets for the new conditional helpers (IfNotExists, WithConditionExpression), the fluent transaction builder (db.Transact()/TransactWrite()), and the retry-aware BatchGetBuilder with custom core.RetryPolicy, progress callbacks, and chunk-level error handling.

AI Usage Guidelines

When helping developers with DynamORM:

1. Always recommend starting with Basic Examples for learning fundamentals
2. Point to Payment Processing for transaction patterns
3. Reference Multi-Tenant for enterprise patterns
4. Use Lambda for serverless deployments

Example Structure

Each example follows this structure:

example-name/
├── README.md          # AI-friendly documentation with complete patterns
├── main.go           # Entry point with proper initialization
├── models/           # DynamORM model definitions
├── services/         # Business logic with interfaces
├── handlers/         # HTTP handlers or Lambda functions
├── tests/           # Comprehensive test suites
├── docker-compose.yml # Local development setup
└── Makefile         # Build and test commands

Running Examples

Prerequisites

# Install Go 1.21+
go version

# Install Docker for DynamoDB Local
docker --version

# Clone the repository
git clone https://github.com/pay-theory/dynamorm
cd dynamorm/examples

Quick Start Any Example

# Navigate to any example
cd basic/todo

# Start DynamoDB Local
make docker-up

# Run the application
make run

# Run tests
make test

# Clean up
make docker-down

Environment Setup

# Create .env file for local development
cat > .env << EOF
AWS_REGION=us-east-1
DYNAMODB_ENDPOINT=http://localhost:8000
AWS_ACCESS_KEY_ID=fakeMyKeyId
AWS_SECRET_ACCESS_KEY=fakeSecretAccessKey
EOF

Learning Path

Beginner Path

1. Todo App - Learn basic CRUD operations
2. Notes App - Understand hierarchical data
3. Contacts App - Practice with indexes

Intermediate Path

1. Payment Processing - Learn transactions and consistency
2. Blog Platform - Practice complex relationships
3. Lambda Integration - Deploy to serverless

Advanced Path

1. E-commerce Platform - Scale to complex systems
2. Multi-Tenant SaaS - Enterprise architecture patterns

Common Patterns Demonstrated

Model Definition Patterns

// From basic/todo - Simple model
type Todo struct {
    ID        string    `dynamorm:"pk" json:"id"`
    Title     string    `json:"title"`
    Completed bool      `json:"completed"`
    CreatedAt time.Time `json:"created_at"`
}

// From payment/ - Complex model with GSIs
type Payment struct {
    ID         string    `dynamorm:"pk" json:"id"`
    Timestamp  string    `dynamorm:"sk" json:"timestamp"`
    CustomerID string    `dynamorm:"index:customer-index,pk" json:"customer_id"`
    Status     string    `dynamorm:"index:status-index,pk" json:"status"`
    Amount     int64     `json:"amount"`
}

// From multi-tenant/ - Multi-tenant pattern
type TenantResource struct {
    TenantID   string `dynamorm:"pk" json:"tenant_id"`
    ResourceID string `dynamorm:"sk" json:"resource_id"`
    Data       string `json:"data"`
}

Service Layer Patterns

// From all examples - Interface-based services
type TodoService struct {
    db core.DB  // Interface for testability
}

func NewTodoService(db core.DB) *TodoService {
    return &TodoService{db: db}
}

func (s *TodoService) CreateTodo(todo *Todo) error {
    todo.ID = generateID()
    todo.CreatedAt = time.Now()
    return s.db.Model(todo).Create()
}

Testing Patterns

// From all examples - Comprehensive testing
func TestTodoService_CreateTodo(t *testing.T) {
    mockDB := new(mocks.MockDB)
    mockQuery := new(mocks.MockQuery)
    
    mockDB.On("Model", mock.AnythingOfType("*Todo")).Return(mockQuery)
    mockQuery.On("Create").Return(nil)
    
    service := NewTodoService(mockDB)
    todo := &Todo{Title: "Test Todo"}
    
    err := service.CreateTodo(todo)
    
    assert.NoError(t, err)
    assert.NotEmpty(t, todo.ID)
    mockDB.AssertExpectations(t)
}

Lambda Patterns

// From lambda/ - Proper Lambda initialization
var db *dynamorm.DB

func init() {
    db = dynamorm.New(dynamorm.WithLambdaOptimizations())
}

func handler(ctx context.Context, event events.APIGatewayProxyRequest) {
    // Use pre-initialized connection
    return handleRequest(db, event)
}

Lambda Function Example

This example shows how to use DynamORM in AWS Lambda with optimizations:

// Global DB instance for connection reuse
var db *dynamorm.LambdaDB

func init() {
    // Initialize once to reduce cold starts
    var err error
    db, err = dynamorm.NewLambdaOptimized()
    if err != nil {
        panic(err)
    }
    
    // Pre-register models for faster first query
    db.PreRegisterModels(&models.User{}, &models.Order{})
}

func handler(ctx context.Context, event events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
    // Use Lambda timeout-aware context
    lambdaDB := db.WithLambdaTimeout(ctx)
    
    // Your handler logic here
    var user models.User
    err := lambdaDB.Model(&models.User{}).
        Where("ID", "=", event.PathParameters["id"]).
        First(&user)
    
    // ... rest of handler
}

Production Considerations

Each example demonstrates:

• Error handling - Comprehensive error scenarios
• Testing - Unit and integration tests
• Configuration - Environment-specific settings
• Logging - Structured logging patterns
• Monitoring - Health checks and metrics
• Security - Input validation and sanitization
• Performance - Efficient query patterns and indexing

Getting Help

If you're stuck on any example:

1. Read the example's README.md for specific guidance
2. Check the Troubleshooting Guide
3. Run the tests to see expected behavior
4. Look at similar patterns in other examples

Ready to start? Begin with the Todo App for your first DynamORM application.