Masterguide: Production SaaS Patterns

Battle-tested patterns extracted from production TypeScript/Next.js and Python/FastAPI applications. Ship enterprise-grade features in hours, not weeks.

49 patterns | ~192 hours total | Copy-paste ready

🚀 Automated Scaffolding (NEW)

For AI Agents: The scaffolding/ directory contains a sequential execution system that scaffolds enterprise-grade infrastructure before you know what you're building.

# AI agents: Execute documents 01-11 in order
# Each document creates working, production-ready code
# Total time: ~2 hours for complete foundation

What it creates:

• Monorepo with Turborepo + pnpm
• Type-safe environment validation
• Shared types and exception taxonomy
• Database schema with RLS policies
• Auth infrastructure with JWT and tier entitlements
• Resilience patterns (circuit breakers, retries, locks)
• Job processing system with state machine
• API foundation with rate limiting
• Structured logging and metrics
• Stripe integration and webhook handling
• Design tokens and base components

See scaffolding/00-MANIFEST.md to get started.

---

What This Is

A curated collection of copy-paste-ready patterns for building production SaaS applications. Every pattern here has been extracted from real, running code—not theoretical best practices.

Philosophy

1. Real Code > Theory - Every pattern includes working code
2. Minimal Dependencies - Prefer stdlib and simple abstractions
3. Production-First - Error handling, edge cases, and observability built-in
4. 48-Hour Rule - Each pattern should be implementable in under 48 hours

Quick Start

# Clone and explore
git clone <repo>
cd Masterguide

# See the full index
cat INDEX.md

# For automated scaffolding, see:
cat scaffolding/00-MANIFEST.md

Repository Structure

Masterguide/
├── scaffolding/         # 🆕 Sequential scaffolding for AI agents
├── 00-foundations/      # Environment, TypeScript, Monorepo, Feature Flags
├── 01-auth/             # Authentication, Authorization, RLS
├── 02-database/         # Migrations, Schema Management
├── 03-resilience/       # Circuit Breakers, Retries, Graceful Degradation
├── 04-workers/          # Background Jobs, Orchestration, DLQ
├── 05-data-pipeline/    # Batch Processing, ETL, Validation
├── 06-api/              # API Design, Idempotency, Rate Limiting
├── 07-realtime/         # SSE, WebSockets, Multiplayer
├── 08-frontend/         # Design Tokens, Mobile, PWA
├── 09-observability/    # Metrics, Health, Anomaly Detection
├── 10-integrations/     # Stripe, OAuth, Webhooks, Email
├── 11-ai/               # Prompt Engine, Provenance, Coaching
├── 12-caching/          # Intelligent Cache
├── 13-data-processing/  # Fuzzy Matching, Scoring, Analytics
├── INDEX.md             # Full searchable index
├── PATTERN_TEMPLATE.md  # Template for new patterns
└── README.md            # This file

Pattern Categories

🏗️ 00-foundations (4 patterns)

Core setup patterns for any project.

Pattern	Time	Description
ENVIRONMENT_CONFIG	2h	Environment variable management
TYPESCRIPT_STRICT	1h	Strict TypeScript configuration
MONOREPO_STRUCTURE	4h	Turborepo/pnpm workspace setup
FEATURE_FLAGS	3h	Feature flag system

🔐 01-auth (5 patterns)

Authentication and authorization.

Pattern	Time	Description
SUPABASE_AUTH	4h	Supabase authentication
JWT_REFRESH_ROTATION	3h	Secure token rotation
MIDDLEWARE_PROTECTION	2h	Route protection
ROW_LEVEL_SECURITY	4h	PostgreSQL RLS
TIER_ENTITLEMENTS	3h	Subscription feature gating

🗄️ 02-database (1 pattern)

Database management.

Pattern	Time	Description
MIGRATIONS	2h	Safe migration patterns

🛡️ 03-resilience (10 patterns)

Fault tolerance and graceful degradation.

Pattern	Time	Description
CIRCUIT_BREAKER	4h	Prevent cascade failures
RETRY_FALLBACK	2h	Exponential backoff
BACKPRESSURE	4h	Buffer management
DISTRIBUTED_LOCK	3h	Redis-based locking
DISTRIBUTED_LOCKING	3h	Async context manager
GRACEFUL_SHUTDOWN	3h	Clean shutdown
LEADER_ELECTION	4h	Single-leader coordination
RESILIENT_STORAGE	6h	Multi-backend failover
ERROR_SANITIZATION	2h	Safe error messages
EXCEPTION_TAXONOMY	2h	Exception hierarchy

⚙️ 04-workers (4 patterns)

Background job processing.

Pattern	Time	Description
ORCHESTRATION	4h	Worker coordination
DEAD_LETTER_QUEUE	3h	Failed job handling
JOB_STATE_MACHINE	4h	Job lifecycle
BACKGROUND_JOB_PROCESSING	4h	General job patterns

📊 05-data-pipeline (7 patterns)

Data processing and ETL.

Pattern	Time	Description
BATCH_PROCESSING	4h	Batched DB operations
CHECKPOINT_RESUME	4h	Exactly-once processing
DEDUPLICATION	4h	Event deduplication
GEOGRAPHIC_CLUSTERING	5h	Geo clustering
SECURE_UPLOAD_PIPELINE	6h	File upload with scanning
SNAPSHOT_AGGREGATION	4h	Daily snapshots
VALIDATION_QUARANTINE	4h	Data validation

🔌 06-api (5 patterns)

API design and client patterns.

Pattern	Time	Description
API_CLIENT	3h	Type-safe API client
IDEMPOTENCY	4h	Idempotent operations
TIER_RATE_LIMITS	4h	Subscription rate limiting
TIER_RATE_LIMITING	4h	Python rate limiting
TRANSFORMERS	2h	Data transformation

📡 07-realtime (5 patterns)

Real-time communication.

Pattern	Time	Description
SSE_STREAMING	3h	Server-Sent Events
SSE_RESILIENCE	3h	Resilient SSE
WEBSOCKET_CONNECTION_MANAGEMENT	4h	WebSocket lifecycle
ATOMIC_MATCHMAKING	6h	Race-free matchmaking
SERVER_AUTHORITATIVE_TICK	8h	Game server loop

🎨 08-frontend (5 patterns)

Frontend architecture.

Pattern	Time	Description
DESIGN_TOKENS	4h	Design token system
DESIGN_TOKEN_SYSTEM	4h	Comprehensive tokens
MOBILE_COMPONENTS	3h	Mobile-first components
PWA_SETUP	2h	Progressive Web App
FIXED_TIMESTEP_GAME_LOOP	4h	Deterministic game loop

📊 09-observability (5 patterns)

Monitoring and alerting.

Pattern	Time	Description
METRICS	3h	Prometheus metrics
HEALTH_MONITORING	4h	Worker health
ANOMALY_DETECTION	5h	Anomaly detection
LOGGING_OBSERVABILITY	3h	Structured logging
FILE_STORAGE	3h	File storage tracking

🔗 10-integrations (4 patterns)

Third-party integrations.

Pattern	Time	Description
STRIPE_INTEGRATION	6h	Stripe payments
OAUTH_INTEGRATION	4h	OAuth providers
WEBHOOK_SECURITY	4h	Secure webhooks
EMAIL_SERVICE	4h	SendGrid email

🤖 11-ai (4 patterns)

AI/ML integration.

Pattern	Time	Description
PROMPT_ENGINE	4h	Prompt management
PROVENANCE_AUDIT	6h	AI audit trail
AI_COACHING_SYSTEM	8h	AI coaching
AI_GENERATION_CLIENT	4h	AI client wrapper

💾 12-caching (1 pattern)

Caching strategies.

Pattern	Time	Description
INTELLIGENT_CACHE	4h	Smart caching

📈 13-data-processing (4 patterns)

Data processing and analysis.

Pattern	Time	Description
MULTI_STAGE_MATCHING	5h	Fuzzy matching
SCORING_ENGINE	4h	Scoring system
ANALYTICS_PIPELINE	6h	Analytics pipeline
COMMUNITY_FEED	4h	Social feed

---

Tech Stack Assumptions

These patterns assume:

• Runtime: Node.js 20+ / Python 3.11+
• Language: TypeScript 5+ (strict mode) / Python with type hints
• Framework: Next.js 16+ (App Router, Turbopack) / FastAPI
• React: React 19+
• Database: PostgreSQL (via Supabase)
• Cache: Redis (optional, patterns degrade gracefully)
• Package Manager: pnpm / pip

Full Index

See INDEX.md for:

• Complete pattern listing with descriptions
• Use-case based navigation
• Cross-references between patterns

Contributing

Each pattern follows the template in PATTERN_TEMPLATE.md.

License

MIT - Use these patterns freely in your projects.