Introduction

This is the backend for Kwai. Check the Architecture page to know how the backend is structured.

Develop

Note

Install Task, when you want to use several automated tasks.

Prerequisites

The backend is written in Python (3.14) and uses uv as project manager.

Clone the monorepo to your system. The backend code is a uv workspace located in the backend directory.

Use uv to install all the dependencies: Make backend the current directory and run:

uv sync --all-packages

This will only install the modules required to run Kwai, for developing add dev and docs dependencies:

uv sync --al-packages --all-groups

Configuration

A kwai.dist.toml file is available to create the configuration file. Copy this file and update it with your configuration. Make sure not to add this file to version control.

Set the full path of the configuration file in the environment variable KWAI_SETTINGS_FILE.

To avoid abuse, make sure that this file is located in a private directory and not available from the internet.

Database

KWAI needs a database. Migration files are available in the directory migrations. Dbmate is used as migration tool.

dbmate -d "./migrations" --url protocol://user:password@host:port/database up

You can also use the task backend:migrate:

task backend:migrate

Note

Create a .env file to avoid entering the dbmate arguments over and over again. See Command line options.

Note

only "up" migrations are provided. Create a backup of the database before running the migrations. Although dbmate can run "down" migrations, they are not used because these are hard to test and can generate more problems than they solve.

Redis

Kwai uses Redis for handling events. When an event is published, it will be put on a stream. Each event will have its own stream. Make sure the settings for redis are set in the configuration file.

A separate process is used to handle the events: kwai_bus.

CLI

A CLI program can be used to test and interrogate the system. See CLI for more information.

Docker

To make testing easier, a docker compose file is provided to set up a container with the required infrastructure. This will install and create the following containers:

• A MySQL database.
• redis for events.
• Mailcatcher for testing emails.

Use a .env file for setting the password for mysql (KWAI_DB_PASSWORD) and redis (KWAI_REDIS_PASSWORD).

Don't add .env to version control!

Tools

The backend is written in Python. The following tools are used to develop kwai: + uv for managing dependencies. + ruff for linter. + pytest for testing the code.

There are pre-commit hooks defined for formatting and linting the code. Use uv to create the pre-commit hooks:

Use the backend folder as working directory for the uv commands.

uv run pre-commit install

Project structure

The kwai API code in the repository is located in the backend folder.

docs

This folder contains all files for creating this documentation site.

migrations

This folder contains the database migrations. Dbmate is used as migration tool.

src

This folder contains the Python code. The system is written following DDD as software development philosophy. Clean code should be the result of following this philosophy. Check the Architecture to know more about this.

The directory tests contains the pytest code for testing the program code.

To run the tests:

uv run pytest src

or use task:

task backend:test

Run

To run the Kwai api server use:

uv run python -m kwai_api

or task:

task backend:run_kwai_api