When you build your first Flask application, you may start with just one Python file:
app.py
For a small learning project, this is completely fine.
But imagine your application later includes:
- User registration and login
- Product management
- REST APIs
- Database models
- Admin functionality
- Email services
- File uploads
- Payment integration
- Templates
- CSS and JavaScript
- Tests
- Development and production configurations
Keeping all of this inside app.py would quickly make the project difficult to understand, debug, test, and maintain.
That is why learning a proper Flask project structure is important.
A good Flask structure separates different responsibilities into appropriate files and folders while keeping related functionality together.
In this guide, you will learn how to organize Flask applications from a simple beginner project to a scalable real-world structure.
What Is a Flask Project Structure?
A Flask project structure is the way you organize the files, folders, modules, configuration, routes, models, templates, services, and other components of a Flask application.
A small application might look like this:
my_flask_app/
│
├── app.py
├── templates/
└── static/
A larger application may look more like:
my_flask_app/
│
├── app/
│ ├── __init__.py
│ ├── models/
│ ├── routes/
│ ├── services/
│ ├── templates/
│ └── static/
│
├── tests/
├── config.py
├── requirements.txt
├── .env
├── .gitignore
└── run.py
Both structures are valid.
The right structure depends on the size and complexity of your application.
Does Flask Require a Specific Project Structure?
No.
One important difference between Flask and more opinionated frameworks is that Flask does not force every application to follow one rigid directory structure.
You decide how your application should be organized.
This gives Flask a lot of flexibility.
However, flexibility can also create problems.
If every feature is placed randomly throughout the project, the application becomes difficult to maintain.
Therefore, although Flask does not require one official structure, professional applications usually follow some common organizational principles:
Separate routes
Separate database models
Separate business logic
Centralize configuration
Group related features
Separate tests
Keep secrets outside source code
The goal is not to create as many folders as possible.
The goal is to make the project understandable.
Why Is Flask Project Structure Important?
Consider a beginner application:
from flask import Flask
app = Flask(__name__)
@app.route("/")
def home():
return "Hello Flask"
There is nothing wrong with keeping this inside app.py.
Now imagine adding:
20 API endpoints
15 database models
Authentication
Email sending
Payments
Admin features
Image uploads
Notifications
Validation
Error handling
One file could quickly become thousands of lines long.
You might end up with:
app.py
├── Database configuration
├── User model
├── Product model
├── Order model
├── Login route
├── Register route
├── Product routes
├── Order routes
├── Payment functions
├── Email functions
├── Admin routes
└── Error handlers
Finding and modifying code becomes increasingly difficult.
A better architecture separates responsibilities:
app/
│
├── models/
│ ├── user.py
│ ├── product.py
│ └── order.py
│
├── routes/
│ ├── auth.py
│ ├── products.py
│ └── orders.py
│
└── services/
├── email_service.py
└── payment_service.py
Now developers can quickly understand where different logic belongs.
Start Simple: Basic Flask Project Structure
Beginners should not start with an unnecessarily complicated architecture.
A good first structure is:
flask_project/
│
├── app.py
│
├── templates/
│ ├── base.html
│ └── index.html
│
├── static/
│ ├── css/
│ │ └── style.css
│ ├── js/
│ │ └── app.js
│ └── images/
│ └── logo.png
│
├── requirements.txt
└── .gitignore
Let’s understand every part.
1. The Project Root Directory
The outer folder is your project root.
Example:
flask_project/
Everything related to your application lives inside this directory.
You might create it with:
mkdir flask_project
cd flask_project
Your root directory commonly contains:
Application package
Configuration
Dependencies
Environment files
Tests
Documentation
Git configuration
Startup files
2. app.py
In beginner projects, app.py is usually the main Flask application file.
Example:
from flask import Flask
app = Flask(__name__)
@app.route("/")
def home():
return "Welcome to Flask"
You can run it using:
flask --app app run
During development:
flask --app app run --debug
The basic responsibility of app.py is to create the Flask application and define or connect application functionality.
For tiny projects, keeping routes here is acceptable.
For larger applications, routes should eventually be moved into separate modules.
3. templates/ Directory
Flask commonly looks for HTML templates inside:
templates/
Example:
templates/
│
├── base.html
├── index.html
├── login.html
├── register.html
└── profile.html
Instead of returning HTML directly:
@app.route("/")
def home():
return "<h1>Home Page</h1>"
you can use:
from flask import render_template
@app.route("/")
def home():
return render_template("index.html")
This keeps Python and HTML separated.
Why Should HTML Be Separate from Python?
You could technically write:
return """
<html>
<body>
<h1>Welcome</h1>
</body>
</html>
"""
But large HTML pages would make Python files difficult to maintain.
A better separation is:
Python
→ Application logic
HTML Templates
→ Page structure
CSS
→ Styling
JavaScript
→ Browser behavior
This separation becomes increasingly valuable as the project grows.
4. base.html
Many Flask websites use template inheritance.
A common file is:
base.html
Example:
<!DOCTYPE html>
<html>
<head>
<title>
{% block title %}My App{% endblock %}
</title>
</head>
<body>
<nav>
<a href="/">Home</a>
<a href="/about">About</a>
</nav>
{% block content %}
{% endblock %}
</body>
</html>
Then index.html can extend it:
{% extends "base.html" %}
{% block title %}
Home
{% endblock %}
{% block content %}
<h1>Welcome to Flask</h1>
{% endblock %}
Instead of repeating navigation, footer, and page structure in every template, they can be defined once.
5. static/ Directory
Files that do not need server-side template processing are usually placed inside:
static/
Typical static files include:
CSS
JavaScript
Images
Icons
Fonts
A clean structure might be:
static/
│
├── css/
│ ├── style.css
│ └── dashboard.css
│
├── js/
│ ├── app.js
│ └── dashboard.js
│
└── images/
├── logo.png
└── banner.webp
You can reference a static file from a template using:
<link
rel="stylesheet"
href="{{ url_for('static', filename='css/style.css') }}"
>
For an image:
<img
src="{{ url_for('static', filename='images/logo.png') }}"
alt="Logo"
>
Using url_for() is preferable to manually hard-coding static paths.
6. requirements.txt
Your Flask application will normally depend on Python packages.
For example:
Flask
SQLAlchemy
Flask-SQLAlchemy
python-dotenv
A requirements.txt file records project dependencies.
Example:
Flask==x.x.x
Flask-SQLAlchemy==x.x.x
python-dotenv==x.x.x
You can create it from your current environment:
pip freeze > requirements.txt
Another developer can then install the dependencies:
pip install -r requirements.txt
This is especially important for:
Team development
Deployment
CI/CD
Docker
Production environments
7. .gitignore
Some files should not be committed to Git.
A .gitignore file tells Git which files and folders to ignore.
Example:
venv/
.venv/
__pycache__/
*.pyc
.env
instance/
.DS_Store
You usually do not want to commit:
Virtual environments
Python cache files
Environment secrets
Local database files
Operating-system metadata
8. Virtual Environment
A virtual environment should generally be used for each Python project.
Create one:
python -m venv venv
Activate on macOS/Linux:
source venv/bin/activate
Windows:
venv\Scripts\activate
Then install Flask:
pip install Flask
Your project may look like:
flask_project/
│
├── venv/
├── app.py
├── templates/
├── static/
├── requirements.txt
└── .gitignore
However, venv/ should normally be ignored by Git.
When Should You Stop Using One app.py File?
There is no exact number of routes that determines when you must restructure your project.
Instead, watch for warning signs:
app.pyis becoming difficult to navigate.- Authentication, products, orders, and admin routes are mixed together.
- Database models are mixed with request handling.
- Functions are becoming difficult to test.
- Multiple developers frequently edit the same file.
- Circular imports start appearing.
- Features cannot be understood independently.
At that point, move toward a package-based architecture.
A Better Flask Project Structure
A more maintainable Flask project might look like:
flask_project/
│
├── app/
│ ├── __init__.py
│ │
│ ├── routes/
│ │ ├── __init__.py
│ │ ├── main.py
│ │ ├── auth.py
│ │ └── products.py
│ │
│ ├── models/
│ │ ├── __init__.py
│ │ ├── user.py
│ │ └── product.py
│ │
│ ├── services/
│ │ ├── email_service.py
│ │ └── payment_service.py
│ │
│ ├── templates/
│ │ ├── base.html
│ │ ├── index.html
│ │ └── auth/
│ │ ├── login.html
│ │ └── register.html
│ │
│ └── static/
│ ├── css/
│ ├── js/
│ └── images/
│
├── tests/
│ ├── test_auth.py
│ └── test_products.py
│
├── config.py
├── requirements.txt
├── .env
├── .gitignore
└── run.py
This may look complicated initially, but each directory has a specific responsibility.
Understanding the app/ Package
Instead of placing all application code in:
app.py
larger Flask applications often create an application package:
app/
Inside it:
app/
└── __init__.py
The presence of __init__.py makes the directory usable as a Python package in the conventional project layout.
Application initialization can then live there.
What Is init.py?
__init__.py is a special Python file commonly used when organizing Python packages.
In Flask applications, it often contains application initialization logic.
For example:
from flask import Flask
def create_app():
app = Flask(__name__)
return app
Now application creation is centralized.
This leads to an important Flask architecture pattern:
The Application Factory Pattern
What Is the Flask Application Factory Pattern?
A simple beginner application often creates the app globally:
from flask import Flask
app = Flask(__name__)
A larger project may instead define:
def create_app():
app = Flask(__name__)
return app
The application is created when the function is called.
Conceptually:
create_app()
↓
Create Flask instance
↓
Load configuration
↓
Initialize extensions
↓
Register Blueprints
↓
Register error handlers
↓
Return application
This is called an application factory.
Why Use an Application Factory?
An application factory can make it easier to create different application instances.
For example:
Development App
Testing App
Production App
It also helps organize:
Configuration
Extensions
Blueprint registration
Testing
Application initialization
This pattern is especially useful as applications grow.
Example Application Factory
Inside:
app/__init__.py
you might write:
from flask import Flask
def create_app():
app = Flask(__name__)
app.config.from_object(
"config.DevelopmentConfig"
)
from app.routes.main import main_bp
app.register_blueprint(main_bp)
return app
Then run.py:
from app import create_app
app = create_app()
Your startup file remains very small.
What Are Flask Blueprints?
Blueprints help organize routes into separate modules.
Suppose your application contains:
Authentication
Products
Orders
Admin
Without Blueprints, all routes might be placed in one file.
With Blueprints:
routes/
│
├── auth.py
├── products.py
├── orders.py
└── admin.py
Each module manages related endpoints.
Blueprint Example
Create:
app/routes/auth.py
Add:
from flask import Blueprint
auth_bp = Blueprint(
"auth",
__name__,
url_prefix="/auth"
)
@auth_bp.route("/login")
def login():
return "Login Page"
@auth_bp.route("/register")
def register():
return "Register Page"
Now register it inside your application factory:
from app.routes.auth import auth_bp
app.register_blueprint(auth_bp)
Routes become:
/auth/login
/auth/register
Why Are Blueprints Useful?
Blueprints help prevent one huge routes file.
Instead of:
routes.py
containing hundreds of routes, you can organize them by feature.
auth.py
users.py
products.py
orders.py
payments.py
admin.py
This improves:
- Navigation
- Maintainability
- Team collaboration
- Feature separation
- Testing
- Scalability
routes/ Directory
The routes/ directory should generally contain request-handling code.
Example:
routes/
│
├── main.py
├── auth.py
├── users.py
├── products.py
└── orders.py
A route should focus primarily on HTTP concerns.
For example:
@products_bp.route(
"/products/<int:product_id>"
)
def get_product(product_id):
product = product_service.get_product(
product_id
)
if product is None:
return {
"error": "Product not found"
}, 404
return product
Notice that the route delegates the actual product logic to a service.
That separation becomes useful in larger applications.
Avoid Putting Too Much Logic in Routes
A common beginner mistake is creating routes that do everything.
For example:
Receive request
Validate input
Query database
Calculate price
Process payment
Send email
Create notification
Format response
all inside one function.
Instead, aim for something like:
Route
↓
Validation
↓
Service
↓
Repository / Model
↓
Database
The exact layers depend on project complexity.
Do not create unnecessary abstractions for tiny projects, but avoid allowing route functions to become unmanageable.
models/ Directory
Database models can be placed inside:
models/
Example:
models/
│
├── user.py
├── product.py
├── order.py
└── payment.py
A model represents application data.
For example, a simplified SQLAlchemy model might look like:
from app.extensions import db
class User(db.Model):
id = db.Column(
db.Integer,
primary_key=True
)
name = db.Column(
db.String(100),
nullable=False
)
email = db.Column(
db.String(255),
unique=True,
nullable=False
)
This represents a database table conceptually similar to:
users
--------------------------------
id | name | email
--------------------------------
1 | Alex | alex@example.com
models/init.py
You may use:
models/__init__.py
to expose models from one place.
For example:
from .user import User
from .product import Product
from .order import Order
Then elsewhere:
from app.models import User
instead of importing each model from its individual module.
Whether you do this depends on the project’s import strategy.
services/ Directory
Business logic should often be separated from route handling.
Example:
services/
│
├── user_service.py
├── email_service.py
├── payment_service.py
└── notification_service.py
Suppose a user registers.
The process may involve:
Validate user
Check duplicate email
Hash password
Create database record
Send welcome email
Instead of placing everything inside:
@auth_bp.route("/register")
you can move business operations into a service.
Conceptually:
Register Route
↓
User Service
↓
Database
↓
Email Service
This keeps route functions easier to understand.
Example Service
class UserService:
def create_user(
self,
name,
email
):
# Validate business rules
# Create user
# Save user
# Return result
pass
The route can then focus on the HTTP layer:
@auth_bp.route(
"/register",
methods=["POST"]
)
def register():
data = request.get_json()
user = user_service.create_user(
data["name"],
data["email"]
)
return {
"id": user.id
}, 201
This separation becomes valuable for testing and maintenance.
repositories/ Directory
Some larger applications introduce a repository layer.
Example:
repositories/
│
├── user_repository.py
├── product_repository.py
└── order_repository.py
Its responsibility is primarily data access.
Conceptually:
Route
↓
Service
↓
Repository
↓
Database
For example:
class UserRepository:
def find_by_email(self, email):
return User.query.filter_by(
email=email
).first()
A service can use the repository without needing to know all database-query details.
However:
Beginners should not add a repository layer simply because it looks professional.
For small applications, direct model access from services may be completely reasonable.
Add architecture only when it solves an actual complexity problem.
extensions.py
Flask applications often use extensions such as:
Flask-SQLAlchemy
Flask-Migrate
Flask-Login
Flask-Caching
Instead of initializing everything inside __init__.py, many projects create:
app/extensions.py
Example:
from flask_sqlalchemy import SQLAlchemy
db = SQLAlchemy()
Then inside the application factory:
from app.extensions import db
def create_app():
app = Flask(__name__)
db.init_app(app)
return app
This pattern helps reduce import problems and keeps extension initialization organized.
Why init_app() Is Useful
Creating an extension like:
db = SQLAlchemy()
without immediately binding it to an application allows it to be initialized later:
db.init_app(app)
This works naturally with application factories.
Conceptually:
Create Extension
↓
Create Flask App
↓
Initialize Extension with App
config.py
Application configuration should be centralized.
Create:
config.py
Example:
import os
class Config:
SECRET_KEY = os.getenv(
"SECRET_KEY"
)
class DevelopmentConfig(Config):
DEBUG = True
class TestingConfig(Config):
TESTING = True
class ProductionConfig(Config):
DEBUG = False
Now different environments can use different settings.
Development, Testing and Production Configuration
Applications commonly behave differently depending on their environment.
For example:
| Setting | Development | Testing | Production |
|---|---|---|---|
| Debug | Yes | Usually No | No |
| Test DB | No | Yes | No |
| Production DB | No | No | Yes |
| Detailed errors | Yes | Controlled | No |
| Secure cookies | Depends | Depends | Yes |
Keeping these configurations separate prevents production-specific settings from being mixed with development settings.
.env File
Environment variables are commonly stored locally in a .env file during development.
Example:
SECRET_KEY=your-secret-key
DATABASE_URL=your-database-url
Then Python can read them through environment-variable tooling.
Important:
.env
should normally be included in:
.gitignore
Never commit real production secrets to a public repository.
.env.example
A useful team-development pattern is to create:
.env.example
Example:
SECRET_KEY=
DATABASE_URL=
MAIL_USERNAME=
MAIL_PASSWORD=
This file shows developers which environment variables are required without exposing actual credentials.
A new developer can copy:
.env.example
to:
.env
and add their own local values.
utils/ Directory
Reusable helper functions may be placed inside:
utils/
Example:
utils/
│
├── validators.py
├── file_helpers.py
└── date_helpers.py
Examples of appropriate utilities:
Validate filename
Format date
Generate random token
Normalize text
But avoid creating a huge utils.py file containing unrelated logic.
If a helper belongs clearly to a specific feature, keeping it with that feature may be better.
validators/ or schemas/ Directory
API applications frequently need request validation.
You may eventually create:
schemas/
│
├── user_schema.py
├── product_schema.py
└── order_schema.py
or:
validators/
The exact name depends on your validation library and architecture.
Their responsibility might include validating:
{
"name": "Alex",
"email": "alex@example.com",
"age": 25
}
before business logic processes it.
This helps prevent invalid client data from reaching deeper layers of the application.
api/ Directory
If your Flask application is mainly a REST API, you may prefer:
app/
│
├── api/
│ ├── auth.py
│ ├── users.py
│ ├── products.py
│ └── orders.py
rather than calling the directory routes.
For versioned APIs:
api/
├── v1/
│ ├── users.py
│ └── products.py
│
└── v2/
├── users.py
└── products.py
Routes might then look like:
/api/v1/users
/api/v1/products
API versioning can help when maintaining compatibility while introducing breaking API changes.
errors/ Directory
Large applications may centralize error handling.
Example:
errors/
│
├── handlers.py
└── exceptions.py
You might define custom exceptions:
class ResourceNotFoundError(Exception):
pass
and register handlers:
@app.errorhandler(
ResourceNotFoundError
)
def handle_not_found(error):
return {
"error": str(error)
}, 404
This avoids repeating the same error response logic across many routes.
tests/ Directory
Tests should normally be separate from production application code.
Example:
tests/
│
├── conftest.py
├── test_auth.py
├── test_users.py
├── test_products.py
└── test_orders.py
Tests might verify:
GET /products returns 200
POST /register creates user
Invalid login returns 401
Missing product returns 404
Normal user cannot access admin endpoint
A clean structure makes individual components easier to test.
conftest.py
When using pytest, projects often use:
tests/conftest.py
for reusable fixtures.
For example, you might create:
Test application
Test client
Temporary database
Authenticated user
and reuse them across multiple test files.
Conceptually:
Test Fixture
↓
Test Client
↓
Flask Application
↓
Route
↓
Assertion
migrations/ Directory
If your application uses a relational database and database migration tooling, you may see:
migrations/
Database schemas change over time.
For example:
Initial users table:
id
name
email
Later you add:
phone
A migration records and applies the schema change.
Conceptually:
Old Database Schema
↓
Migration
↓
New Database Schema
Do not manually recreate production databases whenever your models change.
Use a proper migration strategy.
instance/ Directory
Flask supports an instance folder for files specific to a particular application instance.
It may contain local configuration or application data that should not necessarily live in the source package.
Example:
instance/
├── config.py
└── app.db
The exact use depends on your project.
Local database files or secret configuration inside this directory should normally not be committed unless intentionally required.
uploads/ Directory
If your application accepts uploaded files, you might have:
uploads/
However, storing user uploads directly inside your application repository is usually not ideal for production.
Production applications frequently use dedicated storage such as:
Object storage
Cloud storage
Media servers
CDNs
If local uploads are used during development, keep them separate from application source code.
logs/ Directory
Some deployments may write application logs to files:
logs/
└── app.log
However, many modern production environments send logs to centralized logging systems instead of storing them locally.
Never place sensitive values such as:
Passwords
Access tokens
Secret keys
Payment information
inside logs.
run.py
A project may use:
run.py
as a small entry point.
Example:
from app import create_app
app = create_app()
The important application configuration remains inside the package rather than the startup file.
Depending on your deployment and Flask CLI configuration, you may use different entry-point naming conventions.
A Scalable Flask Project Structure
A reasonably organized larger application could look like:
flask_project/
│
├── app/
│ ├── __init__.py
│ ├── extensions.py
│ │
│ ├── models/
│ │ ├── __init__.py
│ │ ├── user.py
│ │ ├── product.py
│ │ └── order.py
│ │
│ ├── routes/
│ │ ├── __init__.py
│ │ ├── main.py
│ │ ├── auth.py
│ │ ├── users.py
│ │ ├── products.py
│ │ └── orders.py
│ │
│ ├── services/
│ │ ├── user_service.py
│ │ ├── email_service.py
│ │ ├── payment_service.py
│ │ └── order_service.py
│ │
│ ├── repositories/
│ │ ├── user_repository.py
│ │ └── product_repository.py
│ │
│ ├── utils/
│ │ ├── validators.py
│ │ └── helpers.py
│ │
│ ├── templates/
│ │ ├── base.html
│ │ ├── index.html
│ │ └── auth/
│ │ ├── login.html
│ │ └── register.html
│ │
│ └── static/
│ ├── css/
│ ├── js/
│ └── images/
│
├── tests/
│ ├── conftest.py
│ ├── test_auth.py
│ ├── test_users.py
│ └── test_products.py
│
├── migrations/
├── instance/
├── config.py
├── requirements.txt
├── .env
├── .env.example
├── .gitignore
├── README.md
└── run.py
This is not a mandatory Flask structure.
It is an example of how responsibilities can be separated as a project becomes more complex.
Understanding the Request Flow
With a layered structure, a request might travel through the application like this:
Client
↓
HTTP Request
↓
Flask Route / Blueprint
↓
Validation
↓
Service
↓
Repository / Model
↓
Database
↓
Service
↓
Route
↓
HTTP Response
↓
Client
For example:
POST /api/orders
↓
orders.py
↓
OrderService
↓
Product/Order Repository
↓
Database
↓
Order Created
↓
201 Response
This makes responsibilities clearer.
Route vs Service vs Model
This distinction is extremely useful.
Route
Handles HTTP concerns.
Examples:
Read request
Read path/query parameters
Call service
Choose HTTP status
Return response
Service
Handles business rules.
Examples:
Can this order be created?
Is the coupon valid?
Should an email be sent?
How is the final price calculated?
Model / Repository
Handles persistent data.
Examples:
Find user
Create product
Update order
Delete record
A simplified architecture:
Route
↓
Service
↓
Model / Repository
↓
Database
Example: User Registration Structure
Suppose the application receives:
POST /auth/register
The route might:
Read JSON
Validate required fields
Call UserService
Return HTTP response
The service might:
Check duplicate email
Hash password
Create user
Trigger welcome email
The repository/model layer might:
Query existing user
Insert new user
Commit database transaction
The email service might:
Generate email
Send email provider request
Instead of one enormous registration function, responsibilities are distributed logically.
Organizing by Layer vs Organizing by Feature
There are two common ways to structure applications.
Layer-Based Structure
app/
├── routes/
├── models/
├── services/
└── repositories/
All routes live together, all models together, and so on.
This is simple and easy for beginners.
Feature-Based Structure
Large applications may organize files around features instead.
Example:
app/
│
├── auth/
│ ├── routes.py
│ ├── service.py
│ └── models.py
│
├── products/
│ ├── routes.py
│ ├── service.py
│ └── models.py
│
└── orders/
├── routes.py
├── service.py
└── models.py
Now everything related to products is located together.
This can become easier to navigate in large applications.
Which Structure Should Beginners Use?
For learning Flask, start with:
app.py
templates/
static/
Then move to:
app/
├── routes/
├── models/
├── services/
├── templates/
└── static/
Only introduce more layers when you understand why you need them.
A useful progression is:
Stage 1
app.py
↓
Stage 2
app.py
templates/
static/
↓
Stage 3
app/
routes/
models/
templates/
static/
↓
Stage 4
Application Factory
Blueprints
Services
Config
Tests
↓
Stage 5
Feature modules
Repositories
API versioning
Advanced infrastructure
Do not jump directly to Stage 5 for a five-route learning project.
Avoid Overengineering Flask Projects
More folders do not automatically mean better architecture.
This:
controllers/
services/
repositories/
managers/
providers/
helpers/
adapters/
interfaces/
factories/
may be unnecessary for a simple Todo application.
Every layer creates additional complexity.
A good rule is:
Add structure when it makes the code easier to understand, test, reuse, or change.
Do not add abstractions simply because another project uses them.
Circular Imports in Flask
Poor structure can create circular imports.
Example:
app imports routes
routes import app
Python can become stuck because both modules depend on each other.
Application factories and extension initialization patterns help reduce these problems.
Instead of:
db = SQLAlchemy(app)
in a module that may be imported everywhere, use:
db = SQLAlchemy()
and later:
db.init_app(app)
This separates extension creation from application creation.
Naming Files Properly
Use descriptive file names.
Good:
auth.py
products.py
orders.py
payment_service.py
user_repository.py
Less useful:
file1.py
functions.py
stuff.py
new.py
temp.py
A developer should understand the responsibility of a file from its name.
Keep One Responsibility Per Module
Try not to create:
helpers.py
containing:
Password hashing
Payment processing
Date formatting
Email sending
Database queries
Image compression
These functions have unrelated responsibilities.
Prefer:
security.py
payment_service.py
date_helpers.py
email_service.py
image_service.py
when the project is large enough to justify separation.
Where Should Authentication Code Go?
For a medium project:
routes/auth.py
services/auth_service.py
models/user.py
For a feature-based project:
auth/
├── routes.py
├── service.py
├── models.py
└── validators.py
Authentication often includes:
Register
Login
Logout
Password reset
Email verification
Token handling
Session management
Keeping these responsibilities grouped prevents them from spreading randomly across the application.
Where Should API Routes Go?
For a REST API:
routes/
├── users.py
├── products.py
└── orders.py
or:
api/
└── v1/
├── users.py
├── products.py
└── orders.py
If you expect future breaking API versions, versioning can be useful.
For example:
/api/v1/products
Later:
/api/v2/products
Do not introduce API versioning unless your application’s lifecycle requires it.
Where Should Database Queries Go?
Small application:
Route
→ Model
Medium application:
Route
→ Service
→ Model
Large application:
Route
→ Service
→ Repository
→ Model/Database
The correct choice depends on complexity.
Do not create a repository layer merely to wrap every one-line database query.
Where Should Business Logic Go?
Business rules generally should not depend heavily on Flask request objects.
For example, avoid putting all pricing logic directly inside:
@app.route("/checkout")
Instead:
Checkout Route
↓
Checkout Service
↓
Pricing Logic
↓
Payment Service
This makes business logic easier to reuse and test.
Where Should Secrets Go?
Never put production secrets directly in:
config.py
app.py
GitHub repository
Examples include:
Database passwords
JWT secrets
API secrets
Payment keys
Email passwords
Cloud credentials
Use environment variables or a secure secrets-management solution.
Conceptually:
Secret Manager / Environment
↓
Configuration
↓
Flask Application
Where Should Uploaded Files Go?
During development:
uploads/
may be acceptable.
For production, consider external object storage when appropriate.
For example:
Client
↓
Flask
↓
Object Storage
↓
Stored File URL
↓
Database
This is generally more scalable than relying on the local application filesystem, especially in containerized or multi-server deployments.
Where Should Tests Go?
Keep tests clearly separated:
tests/
and organize them by feature:
tests/
├── test_auth.py
├── test_users.py
├── test_products.py
└── test_orders.py
For a larger application:
tests/
├── unit/
├── integration/
└── functional/
You do not need all three categories when starting.
Where Should API Responses Be Formatted?
Small applications may return dictionaries directly from routes.
Large APIs may benefit from dedicated serializers or schemas.
For example:
Database Model
↓
Schema / Serializer
↓
JSON Response
This prevents internal database fields from accidentally becoming part of public API responses.
For example, you definitely do not want to expose:
password_hash
internal_notes
secret_token
because a model was automatically serialized without careful control.
README.md
A professional project should usually contain:
README.md
Useful sections include:
Project Name
Description
Requirements
Installation
Environment Setup
Database Setup
How to Run
How to Test
API Information
Deployment Notes
A new developer should be able to understand how to run the application from the README.
Example Final Beginner-to-Production Structure
For most learning projects, start with:
my_app/
│
├── app.py
├── templates/
├── static/
├── requirements.txt
└── .gitignore
For a growing application:
my_app/
│
├── app/
│ ├── __init__.py
│ ├── extensions.py
│ │
│ ├── routes/
│ ├── models/
│ ├── services/
│ │
│ ├── templates/
│ └── static/
│
├── tests/
├── migrations/
├── config.py
├── requirements.txt
├── .env
├── .env.example
├── .gitignore
├── README.md
└── run.py
For a complex application, you can evolve toward feature-based modules.
Flask Project Structure Best Practices
Follow these practical rules:
- Start simple.
- Separate HTML from Python.
- Keep static assets organized.
- Use a virtual environment.
- Track dependencies.
- Never commit secrets.
- Move routes into Blueprints as the project grows.
- Use an application factory for larger applications.
- Keep database models separate.
- Move complex business logic out of routes.
- Centralize configuration.
- Add tests early.
- Use database migrations.
- Choose descriptive file names.
- Avoid giant utility modules.
- Avoid unnecessary architecture layers.
- Keep related functionality together.
- Design around maintainability rather than folder count.
Common Flask Project Structure Mistakes
Mistake 1: Keeping Everything in app.py
Fine for tutorials, problematic for growing applications.
Mistake 2: Creating Too Many Folders Immediately
A ten-route project probably does not need fifteen architectural layers.
Mistake 3: Hard-Coding Secrets
Never store real credentials in source code.
Mistake 4: Mixing Business Logic with Routes
Routes become difficult to understand and test.
Mistake 5: Putting Database Queries Everywhere
As complexity grows, centralize data-access patterns appropriately.
Mistake 6: Ignoring Tests
Small changes can unexpectedly break unrelated endpoints.
Mistake 7: Committing the Virtual Environment
Commit:
requirements.txt
not:
venv/
Mistake 8: Random File Naming
Use names that describe responsibility.
Mistake 9: Ignoring Environment Differences
Development and production should not necessarily share identical configuration.
Mistake 10: Copying Enterprise Architecture into Tiny Apps
Architecture should solve real problems, not create new ones.
Flask Project Structure Cheat Sheet
| File/Folder | Main Responsibility |
|---|---|
app.py | Simple application entry point |
app/ | Main application package |
__init__.py | Package/application initialization |
routes/ | HTTP routes and Blueprints |
models/ | Database models |
services/ | Business logic |
repositories/ | Data access when needed |
templates/ | Jinja HTML templates |
static/ | CSS, JS, images and assets |
extensions.py | Flask extension instances |
config.py | Application configuration |
.env | Local environment variables/secrets |
.env.example | Example environment-variable names |
tests/ | Automated tests |
migrations/ | Database schema migrations |
instance/ | Instance-specific files/config |
requirements.txt | Python dependencies |
.gitignore | Files Git should ignore |
README.md | Setup and project documentation |
run.py | Application entry point |
Frequently Asked Questions
What is the best Flask project structure?
There is no single best structure for every Flask application.
For beginners, a good starting point is:
app.py
templates/
static/
requirements.txt
As the application grows, introduce packages, Blueprints, models, services, configuration, and tests.
Does Flask require an app.py file?
No.
app.py is a common convention, but Flask applications can use different module and package structures.
What is the app folder in Flask?
In larger applications, app/ commonly contains the main application package, including routes, models, services, templates, and other application code.
What is init.py used for in Flask?
It is a Python package initialization file and is commonly used in Flask projects to hold or expose application initialization logic, including an application factory.
What are Blueprints in Flask?
Blueprints allow related routes and functionality to be organized into reusable modules that are later registered with the Flask application.
Where should Flask models go?
Database models are commonly placed inside:
app/models/
or inside their corresponding feature modules.
Where should Flask routes go?
Small projects may keep routes in app.py.
Larger applications commonly use:
app/routes/
with Blueprints.
Where should Flask business logic go?
Complex business logic is commonly placed in service modules instead of directly inside routes.
Where should Flask templates go?
By convention, templates are usually placed inside:
templates/
Flask can also support Blueprint-specific template organization.
Where should CSS and JavaScript go?
They are usually placed inside:
static/
For example:
static/css/
static/js/
static/images/
Should I use Blueprints in a small Flask app?
Not necessarily.
For a tiny learning project, they may add unnecessary complexity.
Introduce Blueprints when routes and features begin to require clearer separation.
Should I use the application factory pattern?
For very small applications, it is optional.
For larger applications, testing, multiple environments, and modular initialization, the application factory pattern can be very useful.
Should I create services and repositories?
Create them when they improve separation and maintainability.
A service layer is useful when business logic becomes complex.
A repository layer is useful when data-access complexity justifies the abstraction.
Neither should be added automatically to every small project.
Recommended Structure for Beginners
If you are learning Flask today, use this progression.
Phase 1
flask_app/
│
├── app.py
├── templates/
├── static/
└── requirements.txt
Learn:
Routes
Templates
Static files
Forms
Requests
Responses
Phase 2
Move to:
app/
├── __init__.py
├── routes/
├── models/
├── templates/
└── static/
Learn:
Packages
Blueprints
Database models
Application factory
Phase 3
Add:
services/
extensions.py
config.py
tests/
migrations/
Learn:
Business logic
Configuration
Testing
Database migrations
Extension management
Only after you understand these concepts should you consider more advanced architectural layers.
Final Thoughts
Flask does not require one rigid project structure, and that is one of its biggest strengths.
A beginner can start with:
app.py
and build a working application within minutes.
As the project grows, the structure can evolve:
app.py
↓
Templates + Static Files
↓
Application Package
↓
Blueprints
↓
Models
↓
Services
↓
Configuration
↓
Tests
↓
Feature-Based Architecture
The most important lesson is not to create the largest possible folder structure.
It is to make sure every part of the application has a clear responsibility.
A practical Flask application usually aims for a flow such as:
Client
↓
Route / Blueprint
↓
Validation
↓
Business Service
↓
Model / Repository
↓
Database
For a beginner project, keep things simple.
For a growing application, separate responsibilities gradually.
For a production application, focus on maintainability, configuration, security, testing, database migrations, and clear feature boundaries.
A well-designed Flask project structure should make it easy for another developer to open the project and quickly answer three questions:
Where is this feature?
Where should I add new code?
What responsibility does this file have?
If your project structure makes those answers obvious, you are organizing your Flask application correctly.
