🧩 Application Structure with Blueprints

Why Structure Matters

Every Flask project starts as a single app.py. That's fine for a handful of routes. But as features pile up, one giant file starts to hurt:

• Maintainability: scrolling through thousands of lines to find one route
• Collaboration: everyone editing the same file means constant merge conflicts
• Reuse: tightly coupled code can't be lifted into another project
• Testing: you can't test the admin section without loading the entire app
• Circular imports: routes, models, and the app object all reference each other

💡 The city-planning analogy: A village survives with one main street. A city needs zoned districts — residential, commercial, industrial — connected by roads. Blueprints are Flask's zoning: each district (auth, admin, blog) has a clear purpose, yet they all belong to one city.

What Is a Blueprint?

A Blueprint is a self-contained collection of routes, templates, and static files that you define separately and then register onto an application. Think of it as a "mini-app" that doesn't run on its own — it plugs into a real Flask app.

Blueprints shine when your app has distinct sections — an admin panel, a user-facing area, a versioned API — or when several developers each own a slice of the codebase.

Creating & Registering a Blueprint

A blueprint is created much like an app, then decorated with routes using its own .route():

# admin/routes.py
from flask import Blueprint, render_template

# name, import_name, and an optional URL prefix
admin_bp = Blueprint('admin', __name__, url_prefix='/admin')

@admin_bp.route('/')
def index():
    return render_template('admin/index.html')

@admin_bp.route('/users')
def users():
    return render_template('admin/users.html')

The blueprint does nothing until you register it on an app. That's the moment its routes go live:

# app.py
from flask import Flask
from admin.routes import admin_bp

app = Flask(__name__)
app.register_blueprint(admin_bp)

@app.route('/')
def home():
    return 'Home page'

if __name__ == '__main__':
    app.run(debug=True)

Because the blueprint has url_prefix='/admin', its routes resolve to /admin/ and /admin/users. The prefix is applied automatically to every route in the blueprint — you never repeat it.

URL Prefixes & url_for()

When you generate URLs with url_for(), blueprint endpoints are namespaced by the blueprint name — 'blueprint.view':

url_for('home')          # a plain app route
url_for('admin.index')   # the admin blueprint's index view
url_for('admin.users')   # → /admin/users

The same namespacing applies in templates:

<nav>
    <a href="{{ url_for('home') }}">Home</a>
    <a href="{{ url_for('admin.index') }}">Admin</a>
    <a href="{{ url_for('blog.index') }}">Blog</a>
</nav>

Error Handlers & Request Hooks

A blueprint can own behavior that applies only to its routes — which is exactly what you want for a section like an admin panel.

Blueprint-scoped request hooks

A common pattern: guard the entire admin area with one before_request hook, instead of decorating every view:

from flask import abort
from flask_login import current_user

@admin_bp.before_request
def require_admin():
    """Runs before every request to an admin route."""
    if not current_user.is_authenticated or not current_user.is_admin:
        abort(403)   # Forbidden

Blueprint-scoped error handlers

Use app_errorhandler for app-wide handling, or the blueprint-local variant to customize errors just within the blueprint's views:

@admin_bp.errorhandler(403)
def admin_forbidden(error):
    return render_template('admin/errors/403.html'), 403

For truly global handling (like a site-wide 404 page), register on the app itself:

@app.errorhandler(404)
def not_found(error):
    return render_template('errors/404.html'), 404

Project Structure

A well-organized blueprint-based project keeps each concern in its own place. Here is a typical layout:

myapp/
├── run.py                 # entry point
├── config.py              # configuration classes
├── requirements.txt
│
└── app/
    ├── __init__.py        # the application factory (create_app)
    ├── extensions.py      # db, migrate, login_manager instances
    │
    ├── models/            # SQLAlchemy models
    │   ├── __init__.py
    │   └── user.py
    │
    ├── blueprints/
    │   ├── main/          # public pages
    │   │   ├── __init__.py
    │   │   └── routes.py
    │   ├── auth/          # login / register / logout
    │   │   ├── __init__.py
    │   │   ├── routes.py
    │   │   └── forms.py
    │   └── admin/
    │       ├── __init__.py
    │       ├── routes.py
    │       └── templates/admin/
    │
    ├── templates/         # shared templates (base.html, errors/)
    └── static/            # shared css / js / images

To avoid circular imports, a blueprint package's __init__.py typically imports its routes last:

# app/blueprints/main/__init__.py
from flask import Blueprint

main_bp = Blueprint('main', __name__)

from app.blueprints.main import routes  # noqa: E402 — import at the end

The Application Factory

Instead of creating the app object at module load time, the application factory pattern wraps creation in a function. This lets you build fresh app instances with different configs — the key to clean testing.

First, define extensions without an app so they can be shared:

# app/extensions.py
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from flask_login import LoginManager

db = SQLAlchemy()
migrate = Migrate()
login_manager = LoginManager()
login_manager.login_view = 'auth.login'

Then the factory wires everything together and returns the app:

# app/__init__.py
from flask import Flask
from app.extensions import db, migrate, login_manager
from config import config

def create_app(config_name='default'):
    app = Flask(__name__)
    app.config.from_object(config[config_name])

    # Bind extensions to this app instance
    db.init_app(app)
    migrate.init_app(app, db)
    login_manager.init_app(app)

    # Register blueprints
    from app.blueprints.main import main_bp
    from app.blueprints.auth import auth_bp
    from app.blueprints.admin import admin_bp

    app.register_blueprint(main_bp)
    app.register_blueprint(auth_bp, url_prefix='/auth')
    app.register_blueprint(admin_bp, url_prefix='/admin')

    return app

Configuration lives in its own module, one class per environment:

# config.py
import os

class Config:
    SECRET_KEY = os.environ.get('SECRET_KEY', 'dev-key-change-me')
    SQLALCHEMY_TRACK_MODIFICATIONS = False

class DevelopmentConfig(Config):
    DEBUG = True
    SQLALCHEMY_DATABASE_URI = os.environ.get('DEV_DATABASE_URL', 'sqlite:///dev.db')

class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = 'sqlite:///:memory:'

class ProductionConfig(Config):
    SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL')

config = {
    'development': DevelopmentConfig,
    'testing': TestingConfig,
    'production': ProductionConfig,
    'default': DevelopmentConfig,
}

The entry point just calls the factory:

# run.py
import os
from app import create_app

app = create_app(os.environ.get('FLASK_CONFIG', 'default'))

if __name__ == '__main__':
    app.run()

Hands-on Exercise

# app.py (before)
from flask import Flask
app = Flask(__name__)

@app.route('/')
def home(): return 'Home'

@app.route('/login')
def login(): return 'Login'

# app/blueprints/main.py
from flask import Blueprint
main_bp = Blueprint('main', __name__)

@main_bp.route('/')
def home():
    return 'Home'


# app/blueprints/auth.py
from flask import Blueprint
auth_bp = Blueprint('auth', __name__)

@auth_bp.route('/login')
def login():
    return 'Login'


# app/__init__.py
from flask import Flask
from app.blueprints.main import main_bp
from app.blueprints.auth import auth_bp

def create_app():
    app = Flask(__name__)
    app.register_blueprint(main_bp)
    app.register_blueprint(auth_bp, url_prefix='/auth')
    return app


# run.py
from app import create_app
app = create_app()

if __name__ == '__main__':
    app.run(debug=True)

# /auth/login now serves the login view,
# and url_for('auth.login') == '/auth/login'

Summary & Quiz

📚 Further Reading

• Flask docs — Modular Applications with Blueprints
• Flask docs — Application Factories
• Flask official tutorial (uses the factory pattern)

🚀 What's Next?

You've now covered forms, databases, and structure in Flask — a complete toolkit for small-to-medium apps. Next we step up to a "batteries-included" framework and explore Django's architecture, where much of this structure comes built in.