Description

This is the backend template for brainwave a chatgpt like app

Quickstart

• create a copy of .env.example as .env and populate

  cp .env.example .env

Run the app in containers

• Clone the repo and navigate to the root folder.

• To run the app using Docker, make sure you've got Docker installed on your system. From the project's root dirctory, run:

  docker compose up -d

Or, run the app locally

If you want to run the app locally, without using Docker, then:

• Clone the repo and navigate to the root folder.

• Create a virtual environment. Here I'm using Python's built-in venv in a Unix system. Run:

  python3.11 -m venv .venv

• Activate the environment. Run:

  source .venv/bin/activate

• Go to the folder created by cookie-cutter (default is fastapi-nano).

• Install the dependencies. Run:

  pip install -r requirements.txt -r requirements-dev.txt

• Start the app. Run:

  uvicorn app.main:app --port 5000 --reload

Check the APIs

• To play around with the APIs, go to the following link on your browser:

  http://localhost:5000/docs
  

  This will take you to an UI like below:

  

Folder structure

This shows the folder structure of the default template.

fastapi-nano
├── app                           # primary app folder
│   ├── apis                      # this houses all the API packages
│   │    └── api_a                 # api_a package
│   │        ├── __init__.py       # empty init file to make the api_a folder a package
│   │        ├── mainmod.py        # main module of api_a package
│   │        └── submod.py         # submodule of api_a package
│   ├── core                      # this is where the configs live
│   │   ├── auth.py               # authentication with OAuth2
│   │   ├── config.py             # sample config file
│   │   └── __init__.py           # empty init file to make the config folder a package
│   ├── __init__.py               # empty init file to make the app folder a package
│   ├── main.py                   # main file where the fastAPI() class is called
│   ├── routes                    # this is where all the routes live
│   │   └── views.py              # file containing the endpoints of api_a and api_b
│   └── tests                     # test package
│       ├── __init__.py           # empty init file to make the tests folder a package
│       ├── test_api.py           # integration testing the API responses
│       └── test_functions.py     # unit testing the underlying functions
├── dockerfiles                   # directory containing all the dockerfiles
├── .env                          # env file containing app variables
├── Caddyfile                     # simple reverse-proxy with caddy
├── docker-compose.yml            # docker-compose file
├── pyproject.toml                # pep-518 compliant config file
├── requrements-dev.in            # .in file to enlist the top-level dev requirements
├── requirements-dev.txt          # pinned dev dependencies
├── requirements.in               # .in file to enlist the top-level app dependencies
└── requirements.txt              # pinned app dependencies

In the above structure, api_a and api_b are the main packages where the code of the APIs live and they are exposed by the endpoints defined in the routes folder. Here, api_a and api_b have identical logic. Basically these are dummy APIs that take an integer as input and return two random integers between zero and the input value. The purpose of including two identical APIs in the template is to demonstrate how you can decouple the logics of multiple APIs and then assemble their endpoints in the routes directory. The following snippets show the logic behind the dummy APIs.

This is a dummy submodule that houses a function called random_gen which generates a dictionary of random integers.

# This a dummy module
# This gets called in the module_main.py file
from __future__ import annotations
import random


def rand_gen(num: int) -> dict[str, int]:
    num = int(num)
    d = {
        "seed": num,
        "random_first": random.randint(0, num),
        "random_second": random.randint(0, num),
    }
    return d

The main_func in the primary module calls the rand_gen function from the submodule.

from __future__ import annotations
from app.api_a.submod import rand_gen


def main_func(num: int) -> dict[str, int]:
    d = rand_gen(num)
    return d

The endpoint is exposed like this:

# app/routes/views.py
from __future__ import annotations
#... codes regarding authentication ...

# endpoint for api_a (api_b looks identical)
@router.get("/api_a/{num}", tags=["api_a"])
async def view_a(num: int, auth: Depends =Depends(get_current_user)) -> dict[str, int]:
    return main_func_a(num)

So hitting the API with a random integer will give you a response like the following:

{
  "seed": 22,
  "random_first": 27,
  "random_second": 20
}

Further modifications

• You can put your own API logics in the shape of api_a and api_b packages. You'll have to add additional directories like api_a and api_b if you need more APIs.

• Then expose the APIs in the routes/views.py file. You may choose to create multiple views files to organize your endpoints.

• This template uses OAuth2 based authentication and it's easy to change that. FastAPI docs has a comprehensive list of the available authentication options and instructions on how to use them.

• You can change the application port in the .env file.

• During prod deployment, you might need to fiddle with the reverse-proxy rules in the Caddyfile.

Stack

• Caddy
• Docker
• FastAPI
• Gunicorn
• Httpx
• Pip-tools
• Pydantic
• Pytest
• Starlette
• Uvicorn
• PyMongo

Resources

• Flask divisional folder structure
• Deploying APIs built with FastAPI
• Reverse proxying with Caddy

✨ 🍰 ✨