Overview
This document presents the architecture design for a User Service built on the AWS Serverless Framework. The service handles CRUD operations on related User and Email entities, using DynamoDB with a single-table design pattern and AWS Cognito for authentication.Architecture
System components and how they interact
Data Model
DynamoDB single-table design and access patterns
Authentication
Cognito integration and JWT token flow
API Design
Endpoints, validation, and edge cases
Key Requirements
Design Principles
Type Safety First
Type Safety First
Every function, handler, and data model is strongly typed. No
any types. Generics for reusable patterns. Type inference for cleaner consumer code.Single-Table DynamoDB
Single-Table DynamoDB
User and Email entities in one table. Designed for access patterns, not normalized relations. Atomic transactions where needed.
Event-Driven Communication
Event-Driven Communication
Loose coupling via EventBridge. Services react to events, not direct calls. Dead Letter Queues for failure handling.
Defense in Depth
Defense in Depth
JWT validation at API Gateway. User ID from token claims only. Rate limiting on sensitive operations.
Document Structure
Day 1 Scope
This design is time-boxed to a single day of implementation. Below is what would be delivered versus what’s deferred.Day 1 Deliverables
- User CRUD endpoints (
/users/me) - Single primary email per user
- Cognito integration with post-confirmation trigger
- Basic EventBridge publishing (
user.created,user.deleted) - Terraform: Cognito User Pool, DynamoDB table, EventBridge bus
- Serverless Framework: Lambda handlers, API Gateway with authorizer
- Manual deployment to staging
Deferred to Future Iterations
- Multiple emails per user with verification flow
- Transactional outbox pattern (accept at-least-once initially)
- Full CI/CD pipeline with integration tests
- Comprehensive CloudWatch dashboard
- Provisioned concurrency optimization
- Admin endpoints (
GET /users/{userId})