Shopyo Blog

Why Flask Blueprints Aren’t Enough for Large Apps

2026-05-28T00:00:00+00:00

Flask blueprints are the recommended way to organize large Flask applications. They’re a solid tool — but they’re not a complete solution. As your application grows beyond a certain size, blueprints alone leave critical gaps that turn your codebase into technical debt.

This post explains what blueprints do well, where they fall short, and what a complete modular architecture looks like.

What Blueprints Do Well

Blueprints solve the problem of route organization. Instead of one massive app.py with 500 route decorators, you split routes into logical groups:

# auth/views.py
auth_bp = Blueprint("auth", __name__)

@auth_bp.route("/login")
def login(): ...

@auth_bp.route("/register")
def register(): ...

This is a meaningful improvement. It’s the first step every Flask developer should take. But it’s only the first step.

Where Blueprints Fall Short

1. No model isolation

Blueprints only organize views. Your models still live in a single models.py or are scattered across files with no clear ownership. A module that owns its views should also own its models, forms, and templates.

# What most blueprint-based apps look like:
auth/
├── views.py    # routes
models.py        # all models, including auth models
forms.py         # all forms, including auth forms

Auth models shouldn’t live next to billing models any more than auth routes should live next to billing routes.

2. No template encapsulation

Blueprints can have a template_folder, but there’s no convention for how templates should be organized. Without enforced structure, templates end up in a flat directory with hundreds of files and unclear ownership.

3. No auto-discovery

Every blueprint must be manually imported and registered in your app factory:

from auth.views import auth_bp
from billing.views import billing_bp
from dashboard.views import dashboard_bp
# ... 20 more imports

app.register_blueprint(auth_bp)
app.register_blueprint(billing_bp)
app.register_blueprint(dashboard_bp)
# ... 20 more registrations

Forget to import one? Your route silently doesn’t exist. This is fragile and doesn’t scale.

4. No enforcement of module boundaries

Nothing stops billing/views.py from importing auth/models.py directly. Over time, your modules become tightly coupled. You can’t test, refactor, or remove a module without fear.

5. No built-in module assets

Serving static files for a module (CSS, JS, images) requires manual path configuration. There’s no standard way to say “these assets belong to this module.”

The Modular Architecture: Blueprints + Boundaries

The solution isn’t to abandon blueprints — it’s to add the missing layers around them. A true modular architecture adds:

Concern	Blueprints Only	Modular Architecture
Views	✅ Organized	✅ Organized
Models	❌ Global	✅ Per-module
Forms	❌ Global	✅ Per-module
Templates	❌ Flat	✅ Per-module, namespaced
Static assets	❌ Manual	✅ Per-module, auto-served
Auto-discovery	❌ Manual imports	✅ Drop-in registration
Boundary enforcement	❌ None	✅ Convention + tooling
Tests	❌ Centralized	✅ Per-module

How Shopyo Bridges the Gap

Shopyo was built specifically to solve these problems. Every Shopyo module is a self-contained unit with its own views, models, forms, templates, tests, and static assets:

modules/billing/
├── __init__.py
├── view.py        # routes (blueprint)
├── models.py      # billing models only
├── forms.py       # billing forms only
├── global.py      # template variables, configs
├── info.json      # module metadata
├── static/        # billing-specific CSS/JS
├── templates/
│   └── billing/   # namespaced templates
└── tests/
    ├── test_models.py
    └── test_views.py

Modules are auto-discovered — you just drop them in the modules/ folder. The blueprint is registered automatically. Static assets are served transparently in both development and production. Module boundaries are enforced by convention (no cross-module imports) and supported by the framework.

This is what blueprints should have been from the start: a complete unit of functionality, not just a router with a name tag.

Next Steps for Modular Flask

Build Large Flask Apps Without Losing Your Sanity — Build your first modular Flask app
Architecture — How Shopyo’s module system works
Modules/Apps — Creating and managing modules

How to Structure a Flask App That Will Scale to 100k Users

2026-05-28T00:00:00+00:00

You started with a single app.py. It felt clean. Then you added routes. Then a database. Then authentication. By the time you hit 3,000 lines, you couldn’t find anything. By 10,000 lines, you were afraid to touch it.

This is the #1 problem Flask developers face — and there’s almost no good documentation on how to solve it. This guide walks you through a proven architecture that scales from a weekend project to 100,000 users.

The Problem: Flask’s Flexibility Is a Double-Edged Sword

Flask’s greatest strength — minimalism — becomes its greatest weakness as your app grows. The framework gives you blueprints and tells you “good luck.” There’s no enforced structure, no recommended layout for large apps, and no built-in way to organize features into isolated units.

The result? Most large Flask projects end up looking like this:

myapp/
├── app.py           # 5,000 lines
├── models.py        # 2,000 lines
├── forms.py         # 1,000 lines
├── helpers.py       # 800 lines
└── templates/       # 50+ files, no structure
     ├── login.html
     ├── dashboard.html
     ├── admin.html
     └── ...

This doesn’t scale. You can’t find anything. Every change risks breaking something unrelated. New developers on the team spend weeks learning the undocumented structure.

The Solution: Modular Architecture

Instead of organizing by file type (views, models, forms), organize by feature (auth, billing, dashboard, blog). Each feature is a self-contained module with its own views, models, forms, templates, and tests.

myapp/
├── modules/
│   ├── auth/
│   │   ├── view.py
│   │   ├── models.py
│   │   ├── forms.py
│   │   ├── tests/
│   │   └── templates/
│   │       └── auth/
│   ├── billing/
│   │   ├── view.py
│   │   ├── models.py
│   │   ├── forms.py
│   │   ├── tests/
│   │   └── templates/
│   │       └── billing/
│   └── dashboard/
│       ├── view.py
│       ├── models.py
│       ├── tests/
│       └── templates/
│           └── dashboard/
├── app.py
├── config.py
└── requirements.txt

Each module is a Flask blueprint that registers itself. No module imports another module’s internals. Communication happens through events and well-defined interfaces.

Why This Scales

Isolation — A bug in billing/ can’t crash auth/. You can rewrite an entire module without touching the rest of the app.
Discoverability — Need to change how login works? Open modules/auth/view.py. It’s obvious where everything lives.
Testability — Each module has its own tests/ directory. Tests are fast because they only load the module they need.
Team scaling — Five developers can work on five different modules simultaneously with zero merge conflicts.
Reusability — Need auth in your next project? Copy the auth/ module. It’s self-contained.

The Honest Trade-Off

This architecture requires more upfront structure than a single app.py. You need to think about module boundaries before you start coding. For a 100-line API, this is overkill. For anything that will grow beyond a few thousand lines, it’s the difference between a maintainable codebase and a nightmare.

Getting Started Without the Boilerplate

Setting up this architecture manually takes about an hour. You need to:

Create the folder structure
Set up Flask blueprints for each module
Wire up auto-discovery so modules register themselves
Configure static file serving for each module
Set up tests for each module
Add authentication, an admin panel, and user management

Or you can use a framework that does all of this for you.

pip install shopyo
shopyo new myapp
cd myapp && shopyo initialise && flask run

This gives you the architecture above — with auth, admin dashboard, auto-discovery, and scaffolding — running in 30 seconds. Every module you create with shopyo startapp follows the same structure automatically.

The key insight: your project structure should be a feature of your framework, not a decision you make every time you start a project. Shopyo enforces the modular architecture described in this guide so you don’t have to think about it.

How to Add Auth to Flask Without Going Insane

2026-05-28T00:00:00+00:00

Authentication is the most-reimplemented feature in the Flask ecosystem. Every Flask developer has written a login system at least once. Most have written it three or four times, across different projects, with slightly different bugs each time.

This post walks through what a production-grade auth system needs — and how to get it without building it from scratch.

The Minimum Viable Auth Stack

A production-ready auth system needs:

User registration with email verification
Login/logout with session management
Password reset with secure tokens
Password complexity enforcement (length, character classes)
Rate limiting on login and registration endpoints
CSRF protection on all forms
API token authentication for programmatic access
Role-based access control for permissions
Session hardening (HttpOnly, SameSite, Secure cookies)

Let’s look at what it takes to build this from scratch.

Building Auth with Flask Extensions

The standard approach is wiring together several extensions:

pip install flask-login flask-wtf itsdangerous bcrypt email-validator

Then implementing models, forms, views, email-sending, token generation, and rate limiting manually. For a typical app, this is 300-500 lines of code spread across 6-8 files. And you still need to:

Write email templates for verification and password reset
Implement rate limiting with Flask-Limiter
Add password complexity validation
Secure session cookies in config.py
Write the HTML templates for login, register, password reset
Handle edge cases (expired tokens, already-verified users, brute force attempts)

Most Flask auth implementations have at least one of these common bugs:

Timing-attack-vulnerable token comparison
Session fixation
No account lockout
Logging passwords in error messages
Missing CSRF on login forms
Predictable password reset tokens

The Shopyo Approach

Shopyo’s auth module (shopyo_auth) gives you all of the above in one install:

pip install shopyo
shopyo new myapp
cd myapp && shopyo initialise && flask run

This gives you a working auth system at /auth/login, /auth/register, /auth/reset-password — with all of the following built in:

Feature	Status
Email/password registration	✅
Email verification	✅
Password reset flow	✅
Password complexity (min 12 chars, mixed case, digits, symbols)	✅ (default)
Rate limiting (per-endpoint)	✅ (default)
Session cookies (HttpOnly, SameSite=Lax, Secure in prod)	✅
CSRF protection	✅ (global)
API token auth (PBKDF2-HMAC hashed)	✅
Role-based permissions	✅ (policy engine)
Persistent “remember me”	✅
Custom login/register templates	✅

You also get the full test suite — the auth module has 11 test files covering models, forms, roles, tokens, rate limiting, policy, events, and password complexity.

Configuring Auth

Auth behavior is controlled by environment variables and config keys:

# config.py
SHOPYO_AUTH_RATE_LIMIT_LOGIN = "5 per minute"
SHOPYO_AUTH_RATE_LIMIT_REGISTER = "2 per hour"
SHOPYO_AUTH_PASSWORD_COMPLEXITY_ENABLED = True
SHOPYO_AUTH_MIN_PASSWORD_LENGTH = 12
SHOPYO_AUTH_SEED_ADMIN_EMAIL = "admin@example.com"
SHOPYO_AUTH_SEED_ADMIN_PASSWORD = None  # must be set via env

The setup is intentionally secure-by-default. Rate limiting and password complexity are enabled out of the box. Hardcoded secret defaults are removed in v5 — everything comes from environment variables in production.

Why This Matters

Authentication is not a differentiator for your product. It’s table stakes. Every hour you spend debugging password reset tokens is an hour you’re not building features your users actually care about.

Using a pre-built auth system isn’t “lazy” — it’s the responsible choice. The auth module in Shopyo has been tested across multiple Python versions (3.7–3.13), operating systems (Linux, macOS, Windows), and production deployments (Maurilearn.com, FlaskCon.com). It has 71%+ test coverage, a security policy, and active maintenance.

Next Steps for Shopyo Auth

Authentication & Authorization — Deep dive into Shopyo’s auth system
Policy Engine Tutorial — Role-based access control with the policy engine
Quickstart — Get Shopyo running in 10 minutes

Shopyo Blog

Why Flask Blueprints Aren’t Enough for Large Apps

What Blueprints Do Well

Where Blueprints Fall Short

The Modular Architecture: Blueprints + Boundaries

How Shopyo Bridges the Gap

Next Steps for Modular Flask

How to Structure a Flask App That Will Scale to 100k Users

The Problem: Flask’s Flexibility Is a Double-Edged Sword

The Solution: Modular Architecture

Why This Scales

The Honest Trade-Off

Getting Started Without the Boilerplate

Further Reading

How to Add Auth to Flask Without Going Insane

The Minimum Viable Auth Stack

Building Auth with Flask Extensions

The Shopyo Approach

Configuring Auth

Why This Matters

Next Steps for Shopyo Auth