references/architecture-patterns.md
SaaS Architecture Patterns
Overview
This reference covers the key architectural decisions when building SaaS applications. Each pattern includes trade-offs and decision criteria to help teams make informed choices early in the development process.
Multi-Tenancy Models
1. Shared Database (Shared Schema)
All tenants share the same database and tables, distinguished by a tenant_id column.
Pros:
- Lowest infrastructure cost
- Simplest deployment and maintenance
- Easy cross-tenant analytics
- Fastest time to market
Cons:
- Risk of data leakage between tenants
- Noisy neighbor performance issues
- Complex data isolation enforcement
- Harder to meet data residency requirements
Best for: Early-stage products, SMB customers, cost-sensitive deployments
2. Schema-Per-Tenant
Each tenant gets their own database schema within a shared database instance.
Pros:
- Better data isolation than shared schema
- Easier per-tenant backup and restore
- Moderate infrastructure efficiency
- Can customize schema per tenant if needed
Cons:
- Schema migration complexity at scale (N migrations per update)
- Connection pooling challenges
- Database instance limits on schema count
- Moderate operational complexity
Best for: Mid-market products, moderate tenant count (100-1,000)
3. Database-Per-Tenant
Each tenant gets a completely separate database instance.
Pros:
- Maximum data isolation and security
- Per-tenant performance tuning
- Easy data residency compliance
- Simple per-tenant backup/restore
- No noisy neighbor issues
Cons:
- Highest infrastructure cost
- Complex deployment automation required
- Cross-tenant queries/analytics challenging
- Connection management overhead
Best for: Enterprise products, regulated industries (healthcare, finance), high-value customers
Decision Matrix
| Factor | Shared DB | Schema-Per-Tenant | DB-Per-Tenant | |--------|-----------|-------------------|---------------| | Cost | Low | Medium | High | | Isolation | Low | Medium | High | | Scale (tenants) | 10,000+ | 100-1,000 | 10-100 | | Compliance | Basic | Moderate | Full | | Complexity | Low | Medium | High | | Performance | Shared | Moderate | Dedicated |
API-First Design
Principles
- API before UI - Design the API contract before building any frontend
- Versioning from day one - Use URL versioning (
/v1/) or header-based - Consistent conventions - RESTful resources, standard HTTP methods, consistent error format
- Documentation as code - OpenAPI/Swagger specification maintained alongside code
REST API Standards
- Use nouns for resources (
/users,/projects) - Use HTTP methods semantically (GET=read, POST=create, PUT=update, DELETE=remove)
- Return appropriate status codes (200, 201, 400, 401, 403, 404, 429, 500)
- Implement pagination (cursor-based for large datasets, offset for small)
- Support filtering, sorting, and field selection
- Rate limiting with clear headers (X-RateLimit-Limit, X-RateLimit-Remaining)
API Design Checklist
- [ ] OpenAPI 3.0+ specification created
- [ ] Authentication (API keys, OAuth2, JWT) documented
- [ ] Error response format standardized
- [ ] Rate limiting implemented and documented
- [ ] Pagination strategy defined
- [ ] Webhook support for async events
- [ ] SDKs planned for primary languages
Event-Driven Architecture
When to Use
- Decoupling services that evolve independently
- Handling asynchronous workflows (notifications, integrations)
- Building audit trails and activity feeds
- Enabling real-time features (live updates, collaboration)
Event Patterns
- Event Notification: Lightweight event triggers consumer to fetch data
- Event-Carried State Transfer: Event contains all needed data
- Event Sourcing: Store state as sequence of events, derive current state
Implementation Options
- Message Queues: RabbitMQ, Amazon SQS (point-to-point)
- Event Streams: Apache Kafka, Amazon Kinesis (pub/sub, replay)
- Managed PubSub: Google Pub/Sub, AWS EventBridge
- In-App: Redis Streams for lightweight event handling
CQRS (Command Query Responsibility Segregation)
Pattern
- Separate read models (optimized for queries) from write models (optimized for commands)
- Write side handles business logic and validation
- Read side provides denormalized views for fast retrieval
When to Use
- Read/write ratio is heavily skewed (90%+ reads)
- Complex domain logic on write side
- Different scaling needs for reads vs writes
- Multiple read representations of same data needed
When to Avoid
- Simple CRUD applications
- Small-scale applications where complexity is not justified
- Teams without event-driven architecture experience
Microservices vs Monolith Decision Matrix
| Factor | Monolith | Microservices | |--------|----------|--------------| | Team size | < 10 engineers | > 10 engineers | | Product maturity | Early stage, exploring | Established, scaling | | Deployment frequency | Weekly-monthly | Daily per service | | Domain complexity | Single bounded context | Multiple bounded contexts | | Scaling needs | Uniform | Service-specific | | Operational maturity | Low (no DevOps team) | High (platform team) | | Time to market | Faster initially | Slower initially, faster later |
Recommended Path
- Start monolith - Get to product-market fit fast
- Modular monolith - Organize code into bounded contexts
- Extract services - Move high-change or high-scale modules to services
- Full microservices - Only when team and infrastructure justify it
Serverless Considerations
Good Fit
- Infrequent or bursty workloads
- Event-driven processing (webhooks, file processing, notifications)
- API endpoints with variable traffic
- Scheduled jobs and background tasks
Poor Fit
- Long-running processes (>15 min)
- WebSocket connections
- Latency-sensitive operations (cold start impact)
- Heavy compute workloads
Serverless Patterns for SaaS
- API Gateway + Lambda: HTTP request handling
- Event processing: S3/SQS triggers for async work
- Scheduled tasks: CloudWatch Events for cron jobs
- Edge computing: CloudFront Functions for personalization
Infrastructure Recommendations by Stage
| Stage | Users | Architecture | Database | Hosting | |-------|-------|-------------|----------|---------| | MVP | 0-100 | Monolith | Shared PostgreSQL | Single server / PaaS | | Growth | 100-10K | Modular monolith | Managed DB, read replicas | Auto-scaling group | | Scale | 10K-100K | Service extraction | DB per service, caching | Kubernetes / ECS | | Enterprise | 100K+ | Microservices | Polyglot persistence | Multi-region, CDN |