Introduction

A single-file Flask app is fine for experiments, but it becomes difficult to maintain once routes, database logic, and integrations start to grow. Splitting the project into modules improves readability, makes testing easier, and reduces merge conflicts in team environments. The most reliable structure usually combines an app factory, blueprints, and shared extension modules.

Start with a Clear Project Layout

A practical directory structure gives each concern a home and keeps import paths predictable.

1myproject/
2  app/
3    __init__.py
4    config.py
5    extensions.py
6    models.py
7    routes/
8      __init__.py
9      users.py
10      health.py
11    services/
12      user_service.py
13  tests/
14    test_users.py
15  wsgi.py
16  requirements.txt

This structure separates HTTP concerns from business logic and infrastructure code, which makes later refactors much less painful.

Create an App Factory

The app factory creates and configures Flask instances for development, tests, and production without global side effects.

1# app/__init__.py
2from flask import Flask
3from .config import Config
4from .extensions import db
5from .routes.users import users_bp
6from .routes.health import health_bp
7
8
9def create_app(config_class=Config):
10    app = Flask(__name__)
11    app.config.from_object(config_class)
12
13    db.init_app(app)
14
15    app.register_blueprint(users_bp, url_prefix="/users")
16    app.register_blueprint(health_bp)
17
18    with app.app_context():
19        db.create_all()
20
21    return app

Factory style keeps startup deterministic and avoids hidden import-time behavior.

Keep Shared Integrations in One Module

Extension objects such as SQLAlchemy should be declared once and initialized inside create_app.

1# app/extensions.py
2from flask_sqlalchemy import SQLAlchemy
3
4db = SQLAlchemy()

This pattern avoids circular imports that happen when each route file creates its own extension instance.

Split Routes with Blueprints

Blueprints allow route modules to be organized by domain. Keep route handlers thin and delegate work to services.

1# app/routes/users.py
2from flask import Blueprint, jsonify
3from app.services.user_service import list_users
4
5users_bp = Blueprint("users", __name__)
6
7
8@users_bp.get("/")
9def get_users():
10    return jsonify(list_users())

1# app/routes/health.py
2from flask import Blueprint
3
4health_bp = Blueprint("health", __name__)
5
6
7@health_bp.get("/health")
8def health_check():
9    return {"status": "ok"}

Each blueprint should own one coherent area of the API.

Move Business Logic to Services

Services keep non HTTP logic out of route files.

1# app/services/user_service.py
2from app.models import User
3
4
5def list_users():
6    rows = User.query.order_by(User.id.asc()).all()
7    return [{"id": u.id, "name": u.name} for u in rows]

This makes route handlers easier to test and prevents API concerns from leaking into domain logic.

Configure by Environment

Use config classes for predictable values across local, test, and production setups.

1# app/config.py
2import os
3
4
5class Config:
6    SECRET_KEY = os.getenv("SECRET_KEY", "dev-secret")
7    SQLALCHEMY_DATABASE_URI = os.getenv("DATABASE_URL", "sqlite:///app.db")
8    SQLALCHEMY_TRACK_MODIFICATIONS = False
9
10
11class TestConfig(Config):
12    TESTING = True
13    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"

Keep secrets in environment variables, not in source files.

Entry Point and Local Run

A simple entry point connects your factory to Flask CLI.

1# wsgi.py
2from app import create_app
3
4app = create_app()

export FLASK_APP=wsgi:app
flask run

Now the same app object pattern can be reused in deployment servers and tests.

Write Basic Tests Early

Module boundaries are only useful if protected by tests. Add quick route tests to catch registration and import issues.

1# tests/test_users.py
2from app import create_app
3from app.config import TestConfig
4
5
6def test_users_returns_success():
7    app = create_app(TestConfig)
8    client = app.test_client()
9
10    response = client.get("/users/")
11    assert response.status_code == 200

Even a small test set prevents many refactor regressions.

Common Pitfalls

• Importing the Flask app object globally inside route modules, which causes circular imports.
• Putting database and business logic directly in endpoints, making handlers too large.
• Initializing extensions in multiple files instead of a shared module.
• Spreading configuration values across modules with no clear source of truth.
• Forgetting to add __init__.py in package folders, which breaks imports.

Summary

• Use an app factory to create modular, testable Flask apps.
• Organize endpoints with blueprints grouped by domain.
• Keep shared extensions in one place and initialize in the factory.
• Move business rules into service modules to keep routes focused.
• Back the structure with basic tests so refactors remain safe.