AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

saas-scaffolder

Use 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.

Original source
alirezarezvani
License
MIT
Pinned revision
e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read alirezarezvani--saas-scaffolder at revision e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 5

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

  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 |