FastAPI Backend Application Template

This is a template repository aimed to kick-start your project with a setup from a real-world application! This template utilizes the following tech stack:

• 🐳 Dockerized
• 🐘 Asynchronous PostgreSQL
• 🐍 FastAPI

When the Docker is started, these are the URL addresses:

• Backend Application (API docs) $\rightarrow$ http://localhost:8001/docs
• Database editor (Adminer) $\rightarrow$ http//localhost:8081

The backend API without Docker can be found in http://localhost:8000/docs.

Why the above Tech-Stack?

Well, the easy answer is Asynchronousity and Speed!

• FastAPI is crowned as the fastest web framework for Python and thus we use it for our backend development.
• The database of my choice is the asynchronous version of PostgreSQL (via SQLAlchemy 2.0). Read this blog from Packt if you want to educate yourself further about the topic Asynchronous, Synchronous, Concurrency, and Parallelism.
• Docker is a technology that packages an application into standardized units called containers that have everything the software needs to run including libraries, system tools, code, and runtime.

Other Technologies

The above-listed technologies are just the main ones. There are other technologies utilized in this project template to ensure that your application is robust and provides the best possible development environment for your team! These technologies are:

• Pre-Commit CI $\rightarrow$ Continuous integration for our Pre-Commit hook that fixes and updates our hook versions.
• CodeCov $\rightarrow$ A platform that analyzes the result of your automated tests.
• PyTest $\rightarrow$ The testing framework for Python code.
• DBDiagram $\rightarrow$ A platform that lets your design your database by writing SQL and converting it into ERD. This platform provides a complete symbol for entity relationships (not like many other platforms!).
• SQLAlchemy 2.0 $\rightarrow$ The go-to database interface library for Python. The 2.0 is the most recent update where it provides an asynchronous setup.

What Code is included?

For the backend application:

• 3 settings classes (development, staging, production) with the super class in backend/src/config/settings/base.py.
• Event logger in backend/src/config/events.py.
• The Account object table model in backend/src/models/db/account.py.
• The Account object schema model in backend/src/models/schemas/account.py.
• PostgreSQL database connection with asynchronous SQLAlchemy 2.0 in backend/src/repository/database.py.
• A custom SQLAlchemy Base class in backend/src/repository/table.py
• PostgreSQL database connection with asynchronous SQLAlchemy 2.0 in backend/src/repository/database.py.
• Database-related events e.g. database table registration by app startup in backend/src/repository/events.py.
• C. R. U. D. methods for Account object in backend/src/repository/crud/account.py.
• Table classes registration file in backend/src/repository/base.py.
• Alembic setup for auto-generating asynchronous database migrations in backend/src/repository/migration/**.
• Alembic main configuration file in backend/alembic.ini.
• Dependency injection for database session and repository in backend/src/api/**.
• API endpoints for Account signup and signin in backend/src/api/routes/authentication.py.
• API endpoints for Account get all, get 1, update, and delete in backend/src/api/routes/account.py.
• API endpoints registration file in backend/src/api/endpoints.
• Hashing and JWT generators and simple verification functions in backend/src/securities/**.
• Helper functions, string messages, and error handling in backend/src/utilities/**.
• A comprehensive FastAPI application initialization in backend/src/main.py.

For testing, I have prepared the following simple code to kick-start your test-driven development:

• A simple replication of the backend application for testing purposes and the asynchronous test client in backend/tests/conftest.py.
• 2 simple test functions to test the backend application initialization in tests/unit_tests/test_src.py.

For the DevOps:

• A simple build job to test the compilation of the source code for the backend application in .github/workflows/ci-backend.yaml.
• A simple linting job called code-style with black, isort, flake8, and mypy in .github/workflows/ci-backend.yaml.
• An automated testing with PyTest and an automated test reporting with Codecov in in .github/workflows/ci-backend.yaml.
• A source code responsibility distribution file in .github/CODEOWNERS (Please change the username to your own).
• A YAML file for an automated semantic commit message in .github/workflows/ci-backend.yaml.
• An automated test report monitoring via Codecov in codecov.yaml
• A CI for automatically updating all linter version in the pre-commit YAML file in .pre-commit-config.YAML.

For containerization:

• A Docker configuration that utilizes the latest Python image in backend/Dockerfile.
• A script that ensure the backend application will restart when postgres image hasn't started yet in backend/entrypoint.sh.
• Setting up Postgres image for our database server, Adminer for our database editor, and backend_app for our backend application's container in docker-compose.yaml.

For the team development environment:

• A pre-commit hooks for Black, Isort, and MyPy to ensure the conventional commit message before pushing an updated code into the remote repository in .pre-commit-config.YAML.
• All secret variables are listed in .env.example. You need to copy these variables and set the values respectively to your need and save them in a new .env in the root directory.

Setup Guide

This backend application is setup with Docker. Nevertheless, you can see the full local setup without Docker in backend/README.md.

1. Before setting up the backend app, please create a new directory called coverage for the testing report purpose:

   cd backend && mkdir coverage

2. Backend app setup:

   # Install dependencies
   sh init.sh
   
   # Test run your backend server
   uvicorn src.main:backend_app --reload

3. Testing with PyTest: Make sure that you are in the backend/ directory.

   # For testing without Docker
   pytest
   
   # For testing within Docker
   docker exec backend_app pytest

4. Docker setup:

    # Make sure you are in the ROOT project directory
    chmod +x backend/entrypoint.sh
   
    docker-compose build
    docker-compose up
   
    # Every time you write a new code, update your container with:
    docker-compose up -d --build

5. (IMPORTANT) Database setup:

    # (Docker) Generate revision for the database auto-migrations
    docker exec backend_app alembic revision --autogenerate -m "YOUR MIGRATION TITLE"
    docker exec backend_app alembic upgrade head    # to register the database classes
   
    # (Local) Generate revision for the database auto-migrations
    alembic revision --autogenerate -m "YOUR MIGRATION TITLE"
    alembic upgrade head    # to register the database classes

Project Structure

.github/
├── workflows/
    ├── ci-backend.yaml                 # A CI file for the backend app that consists of `build`, `code-style`, and `test`
├── CODEOWNERS                          # A configuration file to distribute code responsibility
├── semantic.yaml                       # A configuration file for ensuring an automated semantic commit message

backend/
├── coverage/
├── src/
    ├── api/
        ├── dependencies/               # Dependency injections
            ├── session.py
            ├──repository.py
        ├── routes/                     # Endpoints
            ├── account.py              # Account routes
            ├── authentication.py       # Signup and Signin routes
        ├── endpoints.py                # Endpoint registration
    ├── config/
        ├── settings/
            ├── base.py                 # Base settings / settings parent class
                ├── development.py      # Development settings
                ├── environments.py     # Enum with PROD, DEV, STAGE environment
                ├── production.py       # Production settings
                ├── staging.py          # Test settings
        ├── events.py                   # Registration of global events
        ├── manager.py                  # Manage get settings
    ├── models/
        ├── db/
            ├── account.py              # Account class for database entity
        ├── schemas/
            ├── account.py              # Account classes for data validation objects
            ├── base.py                 # Base class for data validation objects
    ├── repository/
        ├── crud/
            ├── account.py              # C. R. U. D. operations for Account entity
            ├── base.py                 # Base class for C. R. U. D. operations
        ├── migrations/
            ├── versions/
            ├── env.py                  # Generated via alembic for automigration
            ├── script.py.mako          # Generated via alembic
        ├── base.py                     # Entry point for alembic automigration
        ├── database.py                 # Database class with engine and session
        ├── events.py                   # Registration of database events
        ├── table.py                    # Custom SQLAlchemy Base class
    ├── security/
        ├── hashing/
            ├── hash.py                 # Hash functions with passlib
            ├── password.py             # Password generator with hash functions
        ├── authorizations/
            ├── jwt.py                  # Generate JWT tokens with python-jose
        ├── verifications/
            ├── credentials.py          # Check for attributes' availability
    ├── utilities/
        ├── exceptions/
            ├── http/
                ├── http_exc_400.py     # Custom 400 error handling functions
                ├── http_exc_401.py     # Custom 401 error handling functions
                ├── http_exc_403.py     # Custom 403 error handling functions
                ├── http_exc_404.py     # Custom 404 error handling functions
            ├── database.py             # Custom `Exception` class
            ├── password.py             # Custom `Exception` class
        ├── formatters/
            ├── datetime_formatter.py   # Reformat datetime into the ISO form
            ├── field_formatter.py      # Reformat snake_case to camelCase
        ├── messages/
            ├── http/
                ├── http_exc_details.py	# Custom message for HTTP exceptions
    ├── main.py                         # Our main backend server app
├── tests/
    ├── end_to_end_tests/               # End-to-end tests
    ├── integration_tests/              # Integration tests
    ├── security_tests/                 # Security-related tests
    ├── unit_tests/                     # Unit tests
        ├── test_src.py                 # Testing the src directory's version
    ├── conftest.py                     # The fixture codes and other base test codes
├── Dockerfile                          # Docker configuration file for backend application
├── README.md                           # Documentation for backend app
├── entrypoint.sh                       # A script to restart backend app container if postgres is not started
├── alembic.ini                         # Automatic database migration configuration
├── pyproject.toml                      # Linter and test main configuration file
├── requirements.txt                    # Packages installed for backend app
.dockerignore                           # A file that list files to be excluded in Docker container
.gitignore                              # A file that list files to be excluded in GitHub repository
.pre-commit-config.yaml                 # A file with Python linter hooks to ensure conventional commit when committing
LICENSE.md                              # A license to use this template repository (delete this file after using this repository)
README.md                               # The main documentation file for this template repository
codecov.yaml                            # The configuration file for automated testing CI with codecov.io
docker-compose.yaml                     # The main configuration file for setting up a multi-container Docker

Final Step

You can delete these 3 files (or change its content based on your need):

• LICENSE.md
• README.md
• backend/README.md

Enjoy your development and may your technology be forever useful to everyone 😉🚀🧬

---