The Flask Directory Structure

Whenever I start a new project I always spend some time researching the subject at hand to minimise the risk of having to redo large chunks of the project at a later date. In starting creating this website one of those preparatory subjects was the directory structure of a flask app.

Depending on the use case and size of your app you have a couple of different choices when it comes to your directory structure. Namely, whether you would like to organise your app like a module or a package and if you like a functional or a divisional structure. For the first choice, I would rather put my small application into a larger box knowing it has room to grow than having to rebuild the box to fit the application. Therefore, I recommend to always organise your app as a package. Read more on the differences on the exploreflask website.

The second choice mostly comes down to personal preference but also depends on the use case of your application. The functional structure groups functionally similar code together to increase cohesion between different parts of the app while a divisional structure groups the website by parts to better separate the parts and their code. Read more on the use cases for these structures on the exploreflask website. For me a functional structure seems most logical for the use case of a website.

flask-project/
├── app.py
├── config.py
├── instance/
│   ├── config.py
│   └── default.db
└── website/
    ├── __init__.py
    ├── views/
    │   ├── __init__.py
    │   ├── home.py
    │   └── blog.py
    ├── templates/
    │   ├── base.html
    │   ├── index.html
    │   └── blog/
    │       └── index.html
    ├── static/
    │   ├── css/
    │   │   └── style.css
    │   ├── js/
    │   │   └── base.js
    │   └── resources/
    └── models.py

With my choices of organising my app as a package and using a functional structure the directory tree looks like the one above. Please note that the above tree is a cleaned up version of the real deal.

The base project directory contains the files needed to get the app running. app.py gets an instance of the app from the 'website' package and runs it using the configuration variables set in config.py. The instance/ directory contains additional configuration variables specific to the current environment (e.g. production or development) as well as other environment specific data such as databases.

The website/ package collects the pieces of the app from its sub-directories and packages it for the web server. The package is initiated through the __init__.py file which contains the app factory. The app factory sets up basic functionality and assembles the different app routes as stated in the views/ module. These routes correspond to different urls which gets their html from the templates/ directory. The templates in turn gets their resources such as css, javascript or images from the static/ directory. If your app is using databases to store data (such as this blogpost) the structure of the data is defined in the models.py file.

This was a quick rundown of the basic structure of a web page setup with Flask. In coming blogposts I will do deep dives into each part; both overarching topics such as this one but also specific code snippets and other interesting quirks. Stay tuned!

Cheers,
Theo