alirezarezvani/claude-skills / product-team/skills/saas-scaffolder
saas-scaffolder
VerifiedUse when starting a new SaaS app with auth, database, Stripe billing and a dashboard (Next.js App Router, TypeScript, Tailwind, shadcn/ui, Drizzle). Bootstraps it with project_bootstrapper.py.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.8 KB |
| references/architecture-patterns.md | markdown | 6.6 KB |
| references/auth-billing-guide.md | markdown | 7.0 KB |
| references/saas-architecture-patterns.md | markdown | 2.7 KB |
| references/tech-stack-comparison.md | markdown | 8.8 KB |
| scripts/project_bootstrapper.py | script | 14.1 KB |
references/architecture-patterns.md
View on GitHub# 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
1. **API before UI** - Design the API contract before building any frontend
2. **Versioning from day one** - Use URL versioning (`/v1/`) or header-based
3. **Consistent conventions** - RESTful resources, standard HTTP methods, consistent error format
4. **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
1. **Start monolith** - Get to product-market fit fast
2. **Modular monolith** - Organize code into bounded contexts
3. **Extract services** - Move high-change or high-scale modules to services
4. **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 |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |