Forem: Launchstack310

What Nobody Tells You About Building a SaaS: Auth, Payments, Emails and Infrastructure

Launchstack310 — Wed, 11 Mar 2026 11:43:07 +0000

Building a SaaS is fun… until you reach the boring parts.
Auth. Payments. Emails. Edge cases. Infrastructure.
These are the things that turn a weekend project into weeks of work. Most founders start a SaaS thinking about the product. But the real complexity often comes from everything around it.
Here's what nobody tells you.

Authentication Is Never Just "Login" Everyone thinks auth is a checkbox. It's not. You need:

Email/password login with proper password hashing (bcrypt, not MD5)
OAuth (Google, GitHub) — because users don't want another password
JWT tokens with refresh logic — access tokens expire, and you need to handle that gracefully
Password reset via email with secure, time-limited tokens
Session management — what happens when a user logs in from two devices?
Rate limiting on login endpoints to prevent brute force attacks

In Flask, a minimal JWT setup looks like this:
pythonfrom flask_jwt_extended import JWTManager, create_access_token, jwt_required

jwt = JWTManager(app)

@app.route('/login', methods=['POST'])
def login():
user = verify_credentials(request.json)
access_token = create_access_token(identity=user.id)
return jsonify(access_token=access_token)

@app.route('/protected')
@jwt_required()
def protected():
return jsonify(message="you're in")
Simple. But that's 5% of the work. The other 95% is the edge cases: expired tokens, invalid tokens, revoked tokens, CORS issues in production, OAuth callback URLs, email verification flows...
Most developers spend 1-2 weeks just on auth. And that's before writing a single line of their actual product.

Payments Are Where Things Get Expensive to Get Wrong Stripe is the standard. But wiring it up correctly takes more time than people expect. The basics:

Create a checkout session
Handle the payment success redirect
Store the subscription status in your database

The part that actually matters:

Webhooks — Stripe sends events asynchronously. If your server is down for 10 minutes, you miss them.
Signature verification — anyone can send fake POST requests to your webhook endpoint if you don't verify the Stripe signature
Idempotency — the same webhook event can arrive multiple times. Your handler needs to be idempotent.
Failed payments — what happens when a user's card is declined? Do you downgrade them immediately? Send an email? Give a grace period?
Subscription changes — upgrades, downgrades, cancellations mid-cycle. Proration logic is not fun.

This is the Stripe webhook handler you actually need in production:
python@webhooks_bp.route('/stripe', methods=['POST'])
def stripe_webhook():
payload = request.data
sig_header = request.headers.get('Stripe-Signature')

try:
    event = stripe.Webhook.construct_event(
        payload, sig_header, endpoint_secret
    )
except ValueError:
    return jsonify({'error': 'Invalid payload'}), 400
except stripe.error.SignatureVerificationError:
    return jsonify({'error': 'Invalid signature'}), 400

if event['type'] == 'checkout.session.completed':
    handle_checkout_completed(event['data']['object'])
elif event['type'] == 'customer.subscription.deleted':
    handle_subscription_cancelled(event['data']['object'])

return jsonify({'status': 'ok'})

Skip the signature verification and you're vulnerable. Skip the idempotency and you'll double-charge users. Skip the failed payment handling and you'll lose revenue silently.
Most developers spend another 1-2 weeks on payments. At minimum.

Emails Are a Reliability Problem, Not a Code Problem Sending an email in Python is three lines of code. Sending emails reliably is a different problem. You need transactional emails for:

Email verification on signup
Password reset
Payment confirmation
Subscription renewal reminder
Failed payment notification
Account deletion confirmation

The code is simple with a service like Resend:
pythonimport resend

resend.api_key = os.getenv("RESEND_API_KEY")

def send_purchase_confirmation(to_email, user_name):
resend.Emails.send({
"from": "LaunchStack noreply@launchstack.space",
"to": to_email,
"subject": "Your purchase is confirmed",
"html": f"

Hey {user_name}, you're all set.

"
})
But the real work is:

HTML email templates that look good on all clients (Gmail, Outlook, Apple Mail)
Handling bounces and unsubscribes
Not ending up in spam
Making sure emails actually send when your server is under load

Another few days of work, at minimum.

The Edge Cases Nobody Thinks About
These are the things that will break your app at 2am six months after launch:
User deletes their account — do you hard delete or soft delete? What happens to their data? Their subscription? Their invoices?
Refunds — a user wants their money back. How does that flow through your system? Does it automatically cancel their subscription?
Concurrent requests — two requests hit your server at the same time and both try to update the same user record. Race condition.
Database migrations — you need to add a column to a table that has 50,000 rows. Your app can't go down while this runs.
Token expiry edge cases — user has the app open in two tabs. One tab refreshes the token. The other tab tries to use the old token. What happens?
None of these are hard to solve individually. But each one takes time to think through, implement, and test.
Infrastructure Is the Tax You Pay to Ship
You have a working local app. Now you need to deploy it.

Hosting — Vercel for the Next.js frontend is easy. Flask backend needs a server: Railway, Render, Fly.io, a VPS.
Database — local SQLite is fine for development. Production needs PostgreSQL, proper backups, connection pooling.
Environment variables — you have 15 env vars. Where do they live? How do you manage them across dev, staging, and production?
CORS — your frontend at yourdomain.com can't talk to your backend at api.yourdomain.com until you configure this correctly.
SSL — HTTPS everywhere. Let's Encrypt is free but you need to set it up.
Monitoring — how do you know when your app is down? When an error happens?

This is the CORS config that actually works in production with Flask:
pythonCORS(app, resources={
r"/": {
"origins": "",
"methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
"allow_headers": ["Content-Type", "Authorization"],
"supports_credentials": True,
"max_age": 3600
}
})
Getting infrastructure right is another week of work. Maybe two.

The Real Timeline
Here's what building a SaaS actually looks like for most developers:
TaskExpectedRealityAuthentication2 days1-2 weeksPayments1 day1-2 weeksEmails2 hours2-3 daysInfrastructure1 day1 weekEdge cases—Ongoing
That's 4-6 weeks before you've written a single line of your actual product.

Why SaaS Boilerplates Exist
This is exactly why SaaS boilerplates exist.
Instead of spending weeks setting up authentication, payments, and infrastructure, many founders start from a pre-built foundation that already handles all of this correctly.
That's actually why I built LaunchStack — a production-ready Next.js + Flask boilerplate for Python developers. It comes with JWT auth, Google OAuth, Stripe payments with webhook handling, transactional emails via Resend, and a complete deployment setup.
The goal is simple: skip the boring parts. Start with everything already working. Ship the product you actually want to build.
If you're a Python developer who wants to launch a SaaS without spending weeks on setup, check it out.

Why Setup Hell Kills More SaaS Startups Than Bad Ideas published:

Launchstack310 — Fri, 20 Feb 2026 06:00:11 +0000

Most SaaS startups don't die because the idea was bad.
They die because the founder spent six weeks wiring up JWT refresh tokens, Stripe webhooks, and OAuth callbacks — and never once asked a real person: "Would you pay for this?"
They shipped configuration. Not value.
If you've ever burned two weeks on infrastructure before writing a single line of product code, this post is for you.

Setup Hell Is a Psychology Problem, Not a Technical One
Here's the part nobody talks about: Setup Hell isn't about bad planning. It's about how your brain is wired.
Your brain craves certainty. It wants problems with clear inputs, clear outputs, and a small dopamine hit when the tests pass. Authentication gives you that. Stripe integration gives you that. Even CORS debugging — as painful as it is — gives you that.
You know what doesn't?
Sending a cold DM to a stranger asking if they'd pay for something that doesn't exist. That's rejection territory. That's ambiguity. That's the terrifying possibility that your idea isn't as good as you think.
So instead of doing the uncomfortable thing, you open your terminal. You run create-next-app. You start building auth.
It feels productive. It feels responsible.
It isn't.

Setup feels like progress because it's controllable. Validation feels dangerous because it's not.

Every solved technical problem reinforces the loop. You fix the token rotation bug — you feel competent. You fix the CORS error — you feel productive. Each small win deepens the illusion that you're building a business when you're actually building a shelter.
The most dangerous founders aren't the lazy ones. They're the hardworking ones building the wrong things.
Perfect architecture. Zero users.

What "Just Setting Up Auth and Payments" Actually Costs
Founders consistently underestimate this by 5x. Here's what the timeline actually looks like:
Day 1 — JWT basics. Generate tokens, verify them, protect a route. Feels great.
Day 2 — Refresh tokens. Token rotation, secure storage, race conditions when multiple tabs refresh simultaneously, the httpOnly cookies vs localStorage debate. Twelve conflicting Stack Overflow answers. You pick one.
Day 3 — Password reset. That means email sending. Email sending means an email provider, DNS records, SPF, DKIM — all so your reset emails don't hit spam. Time-limited tokens. Edge cases for duplicate requests.
Day 5 — You haven't written a single line of product code.
But you keep going. You're "almost done."
Day 6-7 — OAuth. Google login seems straightforward until:

Callback URLs behave differently in dev vs production
CORS blocks the redirect
Google's user object doesn't match your email/password schema
You lose an afternoon to a missing trailing slash in allowed origins

Day 8-10 — Stripe. Checkout works locally. Webhooks fire. Beautiful. You deploy and everything breaks:

Wrong webhook URL in production
Signature verification fails because middleware parses the raw body before Stripe's verification step
Three hours on Stack Overflow — the fix is in a 2022 comment
You still need idempotency handling for duplicate events
Environment variables differ across dev, staging, and prod

Day 14 — You have auth, OAuth, Stripe, and a deployment pipeline.
You also have zero users, zero revenue, and zero evidence that anyone wants what you're building.

The False Progress Trap
This is what makes Setup Hell so dangerous. It feels indistinguishable from real work.
What feels like progress:

Implementing JWT refresh token rotation
Perfecting OAuth callback flows
Debugging Stripe webhook signatures
Getting CORS headers exactly right

What actually moves a business forward:

Talking to 10 potential customers
Getting 1 pre-order
Sending 20 cold emails
Shipping a landing page that converts

One list makes you feel good. The other makes you money.

Infrastructure is safe work. Talking to customers is risky work. The safe work will kill your startup.

Early-Stage SaaS Is a Speed Game
The only question that matters in the first 30 days: is there a market here?
Everything that accelerates that answer is valuable. Everything that delays it is waste. It doesn't matter how elegant your waste is.
The math is unforgiving. You have finite energy before life intervenes — savings thin out, motivation fades, the market window shifts. Every day spent on plumbing is a day subtracted from your runway.
And unlike financial runway, motivation runway doesn't show on a spreadsheet. You don't notice it depleting until it's gone.
I've watched talented developers spend three months building technically impressive SaaS products, launch to silence, and quit within two weeks. They burned their creative energy on infrastructure and had nothing left for the unglamorous work of finding customers.
Meanwhile, the founder who shipped a half-broken MVP in ten days is already iterating on real feedback. Their code is worse in every dimension. But they know something priceless: what their users actually want.
The market doesn't care about your architecture. It doesn't care about your test coverage. It doesn't care if your tokens rotate every fifteen minutes or every fifteen hours. The market cares about one thing — does this solve my problem?
You can't answer that from inside your code editor.

Every day spent polishing setup is borrowed from your runway. And the interest rate compounds.

Leverage Compounds. Infrastructure Doesn't.
Not all work hours produce equal results.

An hour debugging CORS misconfig → zero leverage
An hour talking to potential customers → compound leverage
An hour writing content that drives inbound → compound leverage

The difference: leverage keeps working after you stop. Infrastructure doesn't.
The founders who break through ruthlessly protect their highest-leverage hours. They refuse to spend a week on problems that have already been solved. They use existing solutions for the commodity parts — auth, payments, email, deployment — and pour everything into the parts that are genuinely novel.
The parts that only they can build.
This is why smart founders reuse infrastructure aggressively.
Boilerplates. Starter kits. Templates. Anything that buys back time.
Not because they're lazy. Because they understand opportunity cost at a visceral level. Every hour rebuilding Stripe webhook verification for the fourteenth time is an hour not spent on the feature that makes someone pull out their credit card. Every day lost to OAuth debugging is a day your competitor is shipping.
If you can buy back two weeks of setup time, that's two weeks of customer conversations, landing page experiments, and real-world validation. Two weeks that could mean the difference between a launched product and another abandoned repo.
The only part that matters is the 10% only you can build. That's where your startup lives or dies. Not in your JWT implementation. Not in your webhook handler.
This is why production-ready starter stacks exist. But the tool isn't the point. The principle is: stop rebuilding solved problems.
The reason Setup Hell keeps happening isn't lack of discipline. It's that modern SaaS infrastructure is fragmented and heavy. Auth. Payments. Webhooks. Environments. Email. You either rebuild it all yourself or stitch five half-documented tools together and pray they work in production.
This is exactly why we built LaunchStack. A production-ready Flask + Next.js codebase with JWT auth, Stripe payments, OAuth, email, and deployment already wired — so you can skip the plumbing and ship what actually differentiates your product.

Ship or Die
The graveyard of dead SaaS startups is not filled with bad ideas.
It's filled with good ideas that never got a fair shot. Founders who spent their best weeks on problems that were already solved. Who perfected infrastructure for products that never met a customer.
Setup Hell is comfortable. It protects you from the vulnerability of putting something imperfect in front of real people and asking them to pay.
But comfort doesn't build businesses. Velocity does.
You can refactor auth.
You can clean up the code.
You can rebuild the pipeline.
You cannot resurrect a startup that never validated.
Ship the thing. Talk to humans. Get uncomfortable.

If you're about to spend your next two weeks wiring auth and Stripe, ask yourself:
Is this the part only you can build?
→ LaunchStack — Skip setup. Ship product.

How to Structure a Production-Ready Flask SaaS Project (Folder Architecture That Scales)

Launchstack310 — Tue, 17 Feb 2026 07:48:41 +0000

You started with app.py. All your routes in one file. Models at the top, config hardcoded, Stripe webhook handler jammed between the login route and a TODO comment you wrote at 1AM.

It worked. For a while.

Then you added OAuth. Then a webhook handler that needed access to your User model and your email service. Then an admin route that needed authentication middleware. Then environment-specific config for staging vs production. And suddenly, every change required scrolling through 800 lines to find the right section, and every new feature broke something unrelated.

This isn't a Flask problem. Flask gives you freedom. The problem is that no one shows you what production-ready freedom looks like — especially for a SaaS application where authentication, payments, webhooks, and email are first-class concerns from day one.

This is the exact project structure I use for Flask SaaS backends paired with a Next.js frontend. It has survived auth rewrites, Stripe integration, multi-environment deployment, and real production traffic. It scales to 10,000+ users without becoming a maintenance nightmare.

Why Most Flask SaaS Projects Become Unmaintainable

Flask's minimalism is its greatest strength and its most dangerous trap.

The official Flask tutorial gives you a flat structure: auth.py, blog.py, templates/, static/. That's fine for a blog. It's a disaster for a SaaS.

Here's what actually happens when you build a SaaS with a tutorial-grade structure:

Month 1: Everything lives in 3-4 files. You're moving fast. Routes, models, helpers — all accessible, all in one place.

Month 2: You add Stripe. Now your routes.py has authentication endpoints, payment endpoints, webhook handlers, and user profile routes. It's 600+ lines. You start losing track of which functions depend on what.

Month 3: You need to change how you handle Stripe subscription cancellation. The handler is in routes.py, the database update is inline, and the email notification is called directly from the route. You change one thing, break two others.

The root cause is always the same: business logic mixed with route handlers. When your route function handles HTTP parsing, database queries, payment processing, and email sending — you don't have a web application. You have a script that happens to respond to HTTP requests.

The three architectural mistakes that kill Flask SaaS projects

1. No service layer. Route handlers directly query the database, call Stripe, and send emails. Every route becomes a tangled chain of dependencies that's impossible to test or reuse.

2. Flat file organization. All routes in one file, all models in one file. Works until you have 15 models and 40 routes. Then every git merge becomes a conflict.

3. Config hardcoded or scattered. Database URLs in app.py, Stripe keys in routes.py, CORS origins in __init__.py. Deploying to staging vs production becomes a manual find-and-replace operation.

The Production-Ready Architecture Blueprint

Here's the full structure. Every directory has a specific responsibility. Nothing leaks across boundaries.

backend/
├── app/
│   ├── __init__.py              # Application factory
│   ├── extensions.py            # Flask extensions (db, migrate, mail, cors)
│   │
│   ├── config/
│   │   ├── __init__.py
│   │   ├── base.py              # Shared settings
│   │   ├── development.py       # Dev overrides
│   │   ├── production.py        # Prod settings
│   │   └── testing.py           # Test settings
│   │
│   ├── models/
│   │   ├── __init__.py          # Export all models
│   │   ├── user.py              # User + auth fields
│   │   ├── subscription.py      # Stripe subscription data
│   │   └── mixins.py            # Shared model logic (timestamps, soft delete)
│   │
│   ├── routes/
│   │   ├── __init__.py          # Register all blueprints
│   │   ├── auth.py              # Login, register, refresh, logout
│   │   ├── oauth.py             # Google, GitHub OAuth flows
│   │   ├── payments.py          # Checkout, billing, plan management
│   │   ├── webhooks.py          # Stripe webhook handler
│   │   ├── users.py             # Profile, settings, account
│   │   └── admin.py             # Admin-only endpoints
│   │
│   ├── services/
│   │   ├── __init__.py
│   │   ├── auth_service.py      # Token generation, password hashing
│   │   ├── stripe_service.py    # All Stripe API interactions
│   │   ├── email_service.py     # Transactional emails
│   │   └── user_service.py      # User CRUD, account logic
│   │
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── auth.py              # Login/register validation
│   │   ├── user.py              # User response shapes
│   │   └── payment.py           # Payment request validation
│   │
│   ├── middleware/
│   │   ├── __init__.py
│   │   ├── auth_middleware.py   # JWT verification decorator
│   │   └── admin_middleware.py  # Admin role check
│   │
│   └── utils/
│       ├── __init__.py
│       ├── responses.py         # Standardized JSON responses
│       ├── errors.py            # Error handlers
│       └── helpers.py           # Date formatting, slugs, etc.
│
├── migrations/                   # Alembic migration files
├── tests/
│   ├── conftest.py              # Test fixtures
│   ├── test_auth.py
│   ├── test_payments.py
│   └── test_webhooks.py
│
├── .env.development
├── .env.production
├── .env.example
├── requirements.txt
├── wsgi.py                       # Production entry point
└── run.py                        # Development entry point

This isn't theoretical. This is the structure running in production behind a real SaaS application.

Layer-by-layer breakdown

app/__init__.py — The application factory

The application factory pattern is non-negotiable for any serious Flask project. It lets you create multiple app instances with different configs — essential for testing.

# app/__init__.py
import os
from flask import Flask
from app.extensions import db, migrate, cors, mail

def create_app(config_name=None):
    app = Flask(__name__)

    # Load config
    if config_name is None:
        config_name = os.environ.get('FLASK_ENV', 'development')

    app.config.from_object(f'app.config.{config_name}.Config')

    # Initialize extensions
    db.init_app(app)
    migrate.init_app(app, db)
    cors.init_app(app, 
        origins=app.config['ALLOWED_ORIGINS'],
        supports_credentials=True
    )
    mail.init_app(app)

    # Register blueprints
    from app.routes import register_blueprints
    register_blueprints(app)

    # Register error handlers
    from app.utils.errors import register_error_handlers
    register_error_handlers(app)

    return app

app/extensions.py — Extension instances

Extensions are instantiated without an app, then initialized in the factory. This prevents circular imports — one of the most common Flask headaches.

# app/extensions.py
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from flask_cors import CORS
from flask_mail import Mail

db = SQLAlchemy()
migrate = Migrate()
cors = CORS()
mail = Mail()

app/config/ — Environment-specific settings

Never use a single config file with if statements. Separate files per environment. Each inherits from a base.

# app/config/base.py
import os

class Config:
    SECRET_KEY = os.environ.get('SECRET_KEY')
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    JWT_SECRET_KEY = os.environ.get('JWT_SECRET_KEY')

    # Stripe
    STRIPE_SECRET_KEY = os.environ.get('STRIPE_SECRET_KEY')
    STRIPE_WEBHOOK_SECRET = os.environ.get('STRIPE_WEBHOOK_SECRET')

    # Email
    MAIL_SERVER = os.environ.get('MAIL_SERVER')
    MAIL_PORT = int(os.environ.get('MAIL_PORT', 587))

    # CORS
    ALLOWED_ORIGINS = os.environ.get('ALLOWED_ORIGINS', '').split(',')

# app/config/development.py
from app.config.base import Config

class Config(Config):
    DEBUG = True
    SQLALCHEMY_DATABASE_URI = 'sqlite:///dev.db'
    ALLOWED_ORIGINS = ['http://localhost:3000']

# app/config/production.py
import os
from app.config.base import Config

class Config(Config):
    DEBUG = False
    SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL')
    ALLOWED_ORIGINS = [
        'https://yourdomain.com',
        'https://www.yourdomain.com'
    ]

The Service Layer — Why It Changes Everything

The service layer is the single most important architectural decision in this structure, and the one most Flask developers skip.

Without a service layer:

# Route handler doing everything
@auth_bp.route('/api/auth/register', methods=['POST'])
def register():
    data = request.get_json()

    # Validation — in the route
    if not data.get('email') or not data.get('password'):
        return jsonify({'error': 'Missing fields'}), 400

    # Business logic — in the route
    existing = User.query.filter_by(email=data['email']).first()
    if existing:
        return jsonify({'error': 'Email taken'}), 409

    # More business logic — still in the route
    user = User(email=data['email'])
    user.set_password(data['password'])
    db.session.add(user)
    db.session.commit()

    # Token generation — also in the route
    tokens = generate_tokens(user.id)

    # Email — you guessed it, in the route
    send_welcome_email(user.email)

    response = make_response(jsonify({...}))
    response.set_cookie('refresh_token', tokens['refresh_token'], ...)
    return response

With a service layer:

# Route handler — only handles HTTP
@auth_bp.route('/api/auth/register', methods=['POST'])
def register():
    data = request.get_json()

    result, error = auth_service.register_user(
        email=data.get('email'),
        password=data.get('password')
    )

    if error:
        return error_response(error.message, error.status_code)

    response = make_response(success_response(result.user_data))
    response.set_cookie('refresh_token', result.refresh_token, ...)
    return response

# app/services/auth_service.py
def register_user(email, password):
    """Pure business logic. No HTTP. No Flask request/response."""

    if not email or not password:
        return None, ServiceError('Missing fields', 400)

    existing = User.query.filter_by(email=email).first()
    if existing:
        return None, ServiceError('Email already registered', 409)

    user = User(email=email)
    user.set_password(password)
    db.session.add(user)
    db.session.commit()

    tokens = generate_tokens(user.id)
    email_service.send_welcome(user.email)

    return AuthResult(user=user, tokens=tokens), None

The difference:

Routes handle HTTP concerns only: parsing requests, setting cookies, returning responses.
Services handle business logic: validation, database operations, calling other services.
Services are testable without HTTP. You can test register_user() without mocking Flask requests.
Services are reusable. The same register_user() works whether called from a REST endpoint, a CLI command, or a background job.

Structuring the Stripe service

Stripe integration is where clean architecture pays off the most. Every Stripe interaction goes through one service:

# app/services/stripe_service.py
import stripe
import os

stripe.api_key = os.environ.get('STRIPE_SECRET_KEY')

class StripeService:

    @staticmethod
    def create_checkout_session(user, price_id, success_url, cancel_url):
        """Create a Stripe checkout session."""
        return stripe.checkout.Session.create(
            customer_email=user.email,
            payment_method_types=['card'],
            line_items=[{'price': price_id, 'quantity': 1}],
            mode='subscription',
            success_url=success_url,
            cancel_url=cancel_url,
            metadata={'user_id': str(user.id)}
        )

    @staticmethod
    def cancel_subscription(subscription_id):
        """Cancel a Stripe subscription."""
        return stripe.Subscription.modify(
            subscription_id,
            cancel_at_period_end=True
        )

    @staticmethod
    def verify_webhook(payload, sig_header, webhook_secret):
        """Verify and construct a webhook event."""
        return stripe.Webhook.construct_event(
            payload, sig_header, webhook_secret
        )

Now your webhook route is clean:

# app/routes/webhooks.py
@webhooks_bp.route('/api/webhooks/stripe', methods=['POST'])
def stripe_webhook():
    payload = request.data
    sig_header = request.headers.get('Stripe-Signature')

    try:
        event = stripe_service.verify_webhook(
            payload, sig_header, current_app.config['STRIPE_WEBHOOK_SECRET']
        )
    except Exception:
        return error_response('Invalid signature', 400)

    handlers = {
        'checkout.session.completed': handle_checkout,
        'customer.subscription.deleted': handle_cancellation,
        'invoice.payment_failed': handle_payment_failed,
    }

    handler = handlers.get(event['type'])
    if handler:
        handler(event['data']['object'])

    return success_response({'received': True})

For the full implementation of JWT authentication, Stripe webhook verification, and CORS configuration that goes inside this structure, see the companion guide: Flask JWT Authentication, Stripe Webhooks & CORS: The Complete Python SaaS Guide.

What Most Tutorials Get Wrong

Putting everything in `init.py`

The application factory should create the app and register extensions. It should not contain routes, models, or business logic. If your __init__.py is more than 40 lines, you're doing too much there.

Using a single `models.py`

One file works until you have User, Subscription, Invoice, PasswordReset, OAuthToken, and AuditLog models. Split models by domain. Import them all in models/__init__.py so Alembic can detect them:

# app/models/__init__.py
from app.models.user import User
from app.models.subscription import Subscription

# Alembic needs all models imported to detect schema changes
__all__ = ['User', 'Subscription']

Skipping the schema layer

Without input validation, your services accept anything and fail unpredictably. Schemas validate incoming data before it touches business logic:

# app/schemas/auth.py
from dataclasses import dataclass

@dataclass
class RegisterInput:
    email: str
    password: str

    def validate(self):
        errors = []
        if not self.email or '@' not in self.email:
            errors.append('Valid email required')
        if not self.password or len(self.password) < 8:
            errors.append('Password must be at least 8 characters')
        return errors

Hardcoding environment values

Every config value that changes between environments belongs in an environment variable. No exceptions. Not the database URL. Not the Stripe key. Not the CORS origins. Not the JWT secret. If it's hardcoded, it will break when you deploy.

Scaling Considerations

Scaling to a team

This structure makes onboarding straightforward. A new developer needs to understand:

Routes handle HTTP only
Services handle business logic
Models handle data
Config handles environment

They can work on payments.py without understanding oauth.py. They can modify stripe_service.py without touching any route handler. Merge conflicts drop dramatically because concerns live in separate files.

Scaling to features

Adding a new feature follows a predictable pattern:

Create model in models/
Create service in services/
Create routes in routes/
Add schema in schemas/ if needed
Register blueprint in routes/__init__.py

Every feature follows the same pattern. No guessing where code should live.

Scaling to integrations

SaaS applications accumulate integrations: Stripe, email providers, analytics, background jobs. Each integration gets its own service. The service layer acts as an adapter — if you switch from SendGrid to Resend, you change one file. No routes touched.

Scaling to 10,000+ users

At this scale, the structure itself doesn't change. What changes is infrastructure:

Database: Move from SQLite to PostgreSQL (config change only — same SQLAlchemy models)
Caching: Add Redis for session storage and frequently accessed data
Background jobs: Add Celery for email sending and heavy processing
Monitoring: Add structured logging in the service layer

The architecture supports all of this because concerns are already separated. Adding Redis caching to user_service.py doesn't require touching any routes.

Integrating Cleanly with a Next.js Frontend

A Flask SaaS backend paired with Next.js has a specific communication pattern. The structure supports it by design:

All routes return JSON. There are no templates, no server-rendered HTML. The routes/ directory is purely an API layer. Every response follows a consistent shape:

# app/utils/responses.py
def success_response(data, status_code=200):
    return jsonify({
        'status': 'success',
        'data': data
    }), status_code

def error_response(message, status_code=400):
    return jsonify({
        'status': 'error',
        'error': {'message': message}
    }), status_code

CORS is configured once, globally. In extensions.py and initialized in the factory. Not scattered across individual routes.

Authentication flows through middleware. The auth_middleware.py decorator verifies JWT tokens. Routes that need protection simply add the decorator. The frontend sends tokens in the Authorization header. Refresh tokens travel via httpOnly cookies.

Webhooks bypass auth middleware. Stripe webhooks come from Stripe's servers, not from your frontend. The webhooks.py blueprint doesn't use JWT verification — it uses Stripe signature verification instead. Keeping webhooks in a separate blueprint makes this natural.

This clean separation means your Next.js frontend can be developed independently. It talks to a documented JSON API. It doesn't depend on Flask internals, template rendering, or server-side state. You can replace the frontend entirely without touching the backend.

From Architecture to Execution

Good project structure is a force multiplier. It doesn't write your code for you, but it ensures that every line of code you write has a clear place to live, a clear responsibility, and a clear path to scale.

The structure in this guide has been tested across real SaaS applications — from first commit to production deployment to paying users. It handles authentication, payments, webhooks, email, and multi-environment configuration without becoming a maze of interdependent files.

If you're starting a Flask SaaS project today, adopt this structure from the beginning. Migrating a messy codebase into clean architecture is ten times harder than starting clean.

And if you'd rather skip the setup entirely and start with this architecture already built — with JWT authentication, Google and GitHub OAuth, Stripe payments, email system, and admin dashboard all wired together and production-ready — that's exactly what LaunchStack is.

Launching February 24 on Product Hunt. Early bird at $99.

The architecture is the easy part to explain. The hard part is building everything inside it correctly. That's the part that takes weeks.

I wasted 3 weeks on Flask auth before writing a single feature. Here's the production-ready setup.

Launchstack310 — Mon, 16 Feb 2026 08:59:50 +0000

I'm a Python dev building a SaaS.

Here's what my first month actually looked like:

Week 1: JWT auth. Errors I didn't understand.
Week 2: OAuth loops at 2AM.
Week 3: Stripe webhooks failing in production.
Month 1: Still no real feature shipped.

The idea wasn't bad. I was stuck in setup hell.

Most tutorials show "how to make it work" — not how to make it production-safe. So I documented everything that broke, every edge case, every mistake.

Here's the exact production-ready code I ended up with.

The Infrastructure Trap Nobody Warns You About

Flask is minimal by design. That's its strength — and the trap.

With Django, you get auth, admin, and ORM out of the box. With Flask, you build everything from scratch. For a learning project, that's valuable. For a SaaS you're trying to ship, it means weeks of setup before you write a single line of your actual product.

What "setup hell" actually costs you:

Week 1-2: JWT authentication (with OAuth it's 3 weeks)
Week 3: Stripe integration + webhook verification
Week 4: CORS, deployment, environment variables
Week 5+: The idea has lost momentum. Most projects stop here.

Flask JWT Authentication — Production-Ready

Most tutorials give you a single JWT that expires in 7 days. That's a security hole in production.

The correct pattern:

Access token: Short-lived (15 minutes). Stored in memory on the client. Used for every API request.
Refresh token: Long-lived (7-30 days). Stored in an httpOnly cookie. Used only to get new access tokens.

If an access token is stolen, it expires in 15 minutes. The refresh token is never accessible to JavaScript, so XSS attacks can't steal it.

Complete JWT implementation

# auth.py
import jwt
import datetime
from functools import wraps
from flask import request, jsonify, make_response
from models import User

SECRET_KEY = os.environ.get('JWT_SECRET_KEY')
ACCESS_TOKEN_EXPIRY = 15  # minutes
REFRESH_TOKEN_EXPIRY = 30  # days

def generate_tokens(user_id: int) -> dict:
    access_payload = {
        'user_id': user_id,
        'exp': datetime.datetime.utcnow() + datetime.timedelta(minutes=ACCESS_TOKEN_EXPIRY),
        'iat': datetime.datetime.utcnow(),
        'type': 'access'
    }

    refresh_payload = {
        'user_id': user_id,
        'exp': datetime.datetime.utcnow() + datetime.timedelta(days=REFRESH_TOKEN_EXPIRY),
        'iat': datetime.datetime.utcnow(),
        'type': 'refresh'
    }

    return {
        'access_token': jwt.encode(access_payload, SECRET_KEY, algorithm='HS256'),
        'refresh_token': jwt.encode(refresh_payload, SECRET_KEY, algorithm='HS256')
    }

def require_auth(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        auth_header = request.headers.get('Authorization')

        if not auth_header or not auth_header.startswith('Bearer '):
            return jsonify({'error': 'Missing authorization header'}), 401

        token = auth_header.split(' ')[1]

        try:
            payload = jwt.decode(token, SECRET_KEY, algorithms=['HS256'])
            if payload.get('type') != 'access':
                return jsonify({'error': 'Invalid token type'}), 401
            request.user_id = payload['user_id']
        except jwt.ExpiredSignatureError:
            return jsonify({'error': 'Token expired', 'code': 'TOKEN_EXPIRED'}), 401
        except jwt.InvalidTokenError:
            return jsonify({'error': 'Invalid token'}), 401

        return f(*args, **kwargs)
    return decorated

Login endpoint with refresh token in httpOnly cookie

@app.route('/api/auth/login', methods=['POST'])
def login():
    data = request.get_json()
    user = User.query.filter_by(email=data['email']).first()

    if not user or not user.check_password(data['password']):
        return jsonify({'error': 'Invalid credentials'}), 401

    tokens = generate_tokens(user.id)

    response = make_response(jsonify({
        'access_token': tokens['access_token'],
        'user': user.to_dict()
    }))

    response.set_cookie(
        'refresh_token',
        tokens['refresh_token'],
        httponly=True,
        secure=True,
        samesite='Lax',
        max_age=60 * 60 * 24 * 30
    )

    return response

Common JWT errors and exact fixes

DecodeError: Not enough segments

# ❌ Wrong — includes "Bearer " prefix
token = request.headers.get('Authorization')
jwt.decode(token, SECRET_KEY, algorithms=['HS256'])

# ✅ Correct — split and take the token part
auth_header = request.headers.get('Authorization')
token = auth_header.split(' ')[1]

InvalidSignatureError

Your SECRET_KEY is different between environments:

# ❌ Wrong — changes on every restart
SECRET_KEY = os.urandom(32)

# ✅ Correct — consistent across restarts
SECRET_KEY = os.environ.get('JWT_SECRET_KEY')

Token works locally, fails in production

Always use utcnow():

# ✅ Always use utcnow(), never datetime.now()
'exp': datetime.datetime.utcnow() + datetime.timedelta(minutes=15)

Stripe Webhooks — Why Yours Are Failing

Stripe signs every webhook with your endpoint's signing secret. To verify it, you need the raw request body — not the parsed JSON.

This is where most developers break it:

# ❌ Wrong — body already parsed, signature will never match
@app.route('/api/webhooks/stripe', methods=['POST'])
def stripe_webhook():
    data = request.get_json()
    payload = json.dumps(data)
    sig_header = request.headers.get('Stripe-Signature')
    event = stripe.Webhook.construct_event(payload, sig_header, WEBHOOK_SECRET)

# ✅ Correct — raw bytes, never parse first
@app.route('/api/webhooks/stripe', methods=['POST'])
def stripe_webhook():
    payload = request.data  # Raw bytes
    sig_header = request.headers.get('Stripe-Signature')
    event = stripe.Webhook.construct_event(payload, sig_header, WEBHOOK_SECRET)

Production webhook handler

@app.route('/api/webhooks/stripe', methods=['POST'])
def stripe_webhook():
    payload = request.data
    sig_header = request.headers.get('Stripe-Signature')

    try:
        event = stripe.Webhook.construct_event(
            payload, sig_header, WEBHOOK_SECRET
        )
    except ValueError:
        return jsonify({'error': 'Invalid payload'}), 400
    except stripe.error.SignatureVerificationError:
        return jsonify({'error': 'Invalid signature'}), 400

    event_type = event['type']

    if event_type == 'checkout.session.completed':
        handle_checkout_completed(event['data']['object'])
    elif event_type == 'customer.subscription.deleted':
        handle_subscription_cancelled(event['data']['object'])
    elif event_type == 'invoice.payment_failed':
        handle_payment_failed(event['data']['object'])

    return jsonify({'status': 'ok'}), 200

Testing locally with Stripe CLI

# Forward webhooks to your local Flask server
stripe listen --forward-to localhost:5001/api/webhooks/stripe

# Trigger a test event
stripe trigger checkout.session.completed

CORS — Why It Works Locally But Breaks in Production

Locally, browsers are lenient with localhost. In production with HTTPS, CORS becomes strict. Any request with credentials requires explicit Access-Control-Allow-Credentials: true AND a specific origin (wildcards won't work).

# ❌ Wrong — wildcard won't work with credentials
CORS(app, origins="*")

# ✅ Correct — explicit origins with credentials
from flask_cors import CORS

ALLOWED_ORIGINS = [
    "http://localhost:3000",
    "https://yourdomain.com",
    "https://www.yourdomain.com",
]

CORS(app, 
    origins=ALLOWED_ORIGINS,
    supports_credentials=True,
    allow_headers=["Content-Type", "Authorization"],
    methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"]
)

On the Next.js side:

const response = await fetch(`${API_URL}/api/endpoint`, {
  method: 'GET',
  credentials: 'include',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
})

The Real Cost

	Without boilerplate	With production-ready base
Time to first feature	4-8 weeks	Day 1
JWT auth	Build from scratch	Already done
Stripe webhooks	Signature errors, retry loops	Production-ready
CORS	Breaks in production	Configured
OAuth	1-2 weeks per provider	Included

The cost isn't just time. It's momentum. Every week on infrastructure is a week you're not validating your idea.

You Can Build All This Yourself. Or You Can Ship Faster.

Everything in this guide is buildable. The code is here. The patterns are solid.

But you'll spend those days debugging instead of building your product.

That's why I built LaunchStack — a Next.js + Flask boilerplate that ships with all of this pre-configured. JWT auth with refresh tokens, Stripe webhooks, CORS, Google & GitHub OAuth, email system, admin dashboard.

Everything in this article, already working on day one.

Launching February 24. Early bird at $99.

👉 launchstack.space

Have questions about any of the code above? Drop a comment — I'll answer everything.