Structuring a Flask Application

When your project grows beyond a single file, it's time to give it a proper structure. A well-organized project is easier to understand, maintain, and expand.

A common and scalable approach is to turn your application into a package.

A Scalable Project Structure

Here is a typical layout for a medium-sized Flask application:

/myproject
├───/app
│   ├───/__init__.py
│   ├───/routes.py
│   ├───/models.py
│   ├───/static/
│   │   └───style.css
│   └───/templates/
│       ├───base.html
│       └───index.html
├───/venv/
├───config.py
├───run.py
└───requirements.txt

What Each File Does

• run.py: This is the main entry point to start your application. It's often very simple, just importing and running the app instance.

  # run.py
  from app import app
  
  if __name__ == '__main__':
      app.run(debug=True)
  

• config.py: This file contains your application's configuration, such as the SECRET_KEY, database URI, and other settings. Keeping configuration separate makes the app more portable.

  # config.py
  import os
  
  class Config:
      SECRET_KEY = os.environ.get('SECRET_KEY') or 'you-will-never-guess'
      # ... other config variables
  

• requirements.txt: As you know, this file lists all the project's dependencies.

• /app directory (the package):

  • __init__.py: This file does two things: it tells Python that the app directory should be treated as a package, and it's where you will create your Flask app instance. This is also where you'll import your configuration and initialize extensions.

    # app/__init__.py
    from flask import Flask
    from config import Config
    
    app = Flask(__name__)
    app.config.from_object(Config)
    
    from app import routes, models
    

    Note: The from app import routes is at the bottom to avoid circular import errors.

  • routes.py (or views.py): This file will contain all your application's routes (the functions decorated with @app.route()).

  • models.py: If you are using a database, this is where you would define your database models or schemas.

  • static/ and templates/: These folders contain your static files (CSS, JS, images) and Jinja templates, just like in a single-file app.

Flask Blueprints for Larger Apps

When you have many routes, you might want to group them. For example, you could have one set of routes for user authentication (/login, /register) and another for handling blog posts.

Flask Blueprints are the answer. They allow you to organize your application into distinct components. You can think of a Blueprint as a mini-application within your main project. Each blueprint can have its own routes, templates, and static files. This is the standard way to build large, maintainable Flask applications.