🏗️ Setting Up a Flask Application

Why Structure Matters

Flask deliberately does not impose a project layout — which is freeing until your one-file app hits 800 lines and you can't find anything. A thoughtful structure isn't about tidiness for its own sake; it directly buys you:

• Maintainability — related code lives together, so changes are easy to locate.
• Scalability — the app can grow feature by feature without becoming a tangle.
• Collaboration — teammates work in separate files without stepping on each other.
• Testability — the factory pattern lets tests spin up isolated app instances.
• Clean deployment — configuration and secrets stay out of the code.

💡 Rule of thumb: match the structure to the app. Start simple and refactor upward as it grows — you don't need blueprints and a factory for a 30-line prototype, but you'll be glad of them at 3,000 lines.

Virtual Environments & Dependencies

A virtual environment is an isolated Python installation for a single project. It keeps each project's packages separate so an upgrade in one app can't break another. Always create one before installing anything.

# Create a virtual environment in a folder named .venv
python -m venv .venv

# Activate it — macOS / Linux
source .venv/bin/activate

# Activate it — Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Install Flask
pip install flask

# Record exact versions so others can reproduce your setup
pip freeze > requirements.txt

# Later, on another machine:
pip install -r requirements.txt

Three Project Structures

As an app grows it typically climbs a ladder of three structures. Here's when to use each.

1. Single module — prototypes & scripts

Everything in one app.py. Perfect for demos and learning.

# app.py
from flask import Flask, render_template

app = Flask(__name__)


@app.route("/")
def home():
    return render_template("home.html")

2. Package — small to medium apps

Move the app into an app/ package so models, routes, and templates each get their own file.

project/
├── app/
│   ├── __init__.py      # creates the app
│   ├── routes.py        # view functions
│   ├── models.py        # database models
│   ├── static/          # css, js, images
│   └── templates/       # Jinja2 templates
├── config.py            # configuration classes
├── run.py               # entry point
└── requirements.txt

3. Application factory + blueprints — large / team apps

The app is built by a create_app() function, and routes are grouped into blueprints (auth, main, admin…). This is the target structure for serious projects and the one this course uses going forward.

project/
├── app/
│   ├── __init__.py      # create_app() factory
│   ├── extensions.py    # db, migrate, login_manager objects
│   ├── models.py
│   ├── main/            # a blueprint
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   └── templates/main/
│   ├── auth/            # another blueprint
│   │   ├── __init__.py
│   │   └── routes.py
│   ├── static/
│   └── templates/       # shared base.html
├── config.py
├── run.py
└── requirements.txt

The Application Factory

The application factory is a function — conventionally create_app() — that builds and returns a configured Flask app. Instead of a module-level app = Flask(__name__) global, you construct the app on demand.

# app/__init__.py
from flask import Flask
from app.extensions import db, migrate
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
    db.init_app(app)
    migrate.init_app(app, db)

    # Register blueprints
    from app.main import bp as main_bp
    app.register_blueprint(main_bp)

    return app

# app/extensions.py — extension objects live here, unbound
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate

db = SQLAlchemy()
migrate = Migrate()

Configuration Management

Different environments need different settings: debug on locally, a throwaway database in tests, real secrets in production. The clean pattern is a base Config class that each environment subclasses.

# config.py
import os
from dotenv import load_dotenv

basedir = os.path.abspath(os.path.dirname(__file__))
load_dotenv(os.path.join(basedir, ".env"))


class Config:
    """Settings shared by every environment."""
    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("DATABASE_URL") or \
        "sqlite:///" + os.path.join(basedir, "dev.db")


class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
    WTF_CSRF_ENABLED = False


class ProductionConfig(Config):
    DEBUG = False
    SQLALCHEMY_DATABASE_URI = os.environ.get("DATABASE_URL")


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

Secrets and machine-specific values come from a .env file, read at startup by python-dotenv:

# .env  — NEVER commit this file
SECRET_KEY=a-long-random-string
DATABASE_URL=sqlite:///app.db
FLASK_DEBUG=1

The Developer Workflow

Once the scaffold exists, day-to-day work settles into a rhythm. The Flask CLI drives most of it.

# Tell Flask where the app is (or use --app on each command)
export FLASK_APP=run.py

# Run the auto-reloading dev server
flask run --debug

# Open an interactive shell with your app context loaded
flask shell

# Database migrations (with Flask-Migrate)
flask db migrate -m "Add users table"
flask db upgrade

# Run the test suite
pytest

The flask shell command is especially handy — it drops you into Python with the app context already active. Register commonly-used objects so they're waiting for you:

# in create_app(), or run.py
@app.shell_context_processor
def make_shell_context():
    return {"db": db, "User": User}

Full Project Walkthrough

Let's assemble a complete package-structured app end to end. First, the scaffold:

python -m venv .venv
source .venv/bin/activate
pip install flask flask-sqlalchemy flask-migrate python-dotenv

mkdir -p myapp/app/static/css myapp/app/templates
cd myapp
touch app/__init__.py app/routes.py app/models.py \
      app/extensions.py config.py run.py .env .gitignore
pip freeze > requirements.txt

The application factory, wiring in the config and models:

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


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

    db.init_app(app)
    migrate.init_app(app, db)

    from app import routes  # register view functions
    app.register_blueprint(routes.bp)

    return app

A model — note it imports db from extensions, avoiding circular imports:

# app/models.py
from datetime import datetime, timezone
from app.extensions import db


class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(64), unique=True, index=True)
    email = db.Column(db.String(120), unique=True, index=True)
    created_at = db.Column(
        db.DateTime, default=lambda: datetime.now(timezone.utc)
    )

    def __repr__(self):
        return f"<User {self.username}>"

Routes grouped in a small blueprint:

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

bp = Blueprint("main", __name__)


@bp.route("/")
def home():
    return render_template("home.html", title="Home")


@bp.route("/about")
def about():
    return render_template("about.html", title="About")

The entry point, choosing a config from the environment:

# run.py
import os
from app import create_app

app = create_app(os.getenv("FLASK_CONFIG", "default"))

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

Run it with flask --app run run --debug, initialize the database with flask db init && flask db migrate && flask db upgrade, and you have a real, extensible foundation.

 * Serving Flask app 'run'
 * Debug mode: on
 * Running on http://127.0.0.1:5000
 * Restarting with stat

Hands-on Exercise

# config.py
class Config:
    SECRET_KEY = "dev-key-change-me"


class DevelopmentConfig(Config):
    DEBUG = True


class TestingConfig(Config):
    TESTING = True


config = {
    "development": DevelopmentConfig,
    "testing": TestingConfig,
    "default": DevelopmentConfig,
}


# app/__init__.py
from flask import Flask, Blueprint, render_template
from config import config

bp = Blueprint("main", __name__)


@bp.route("/")
def home():
    return render_template("home.html")


@bp.route("/about")
def about():
    return "About this blog."


def create_app(config_name="default"):
    app = Flask(__name__)
    app.config.from_object(config[config_name])
    app.register_blueprint(bp)
    return app


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

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

Summary & Quiz

📚 Further Reading

• Flask — Application Factories
• Flask — Configuration Handling
• Flask — Command Line Interface
• Flask-Migrate Documentation

🚀 What's Next?

With a project scaffold in place, we turn to the heart of any web app: routing. Next we explore how Flask maps URLs to view functions, captures dynamic URL parts, and returns every kind of response.