Python Clean Architecture

This project aims to provide a template for clean architecture in Python applications.

Table of Contents

• Python Clean Architecture
  • Table of Contents
  • Description
  • Getting Started
    • Setup Environment Variables
    • Quick Start with Docker Compose
    • Database Setup
    • Start the Server
      • With uv
      • With VSCode Debugger
    • Running Tests
      • With uv in Command Line
      • With Docker
    • API Documentation
  • Editor Integration

Description

The main idea of Clean Architecture by Robert C. Martin (Uncle Bob) is to separate the concerns of the application into different layers, so that the application is more maintainable and scalable. Here are the main principles of clean architecture from the original article:

• Independent of Frameworks. The architecture does not depend on the existence of some library of feature laden software. This allows you to use such frameworks as tools, rather than having to cram your system into their limited constraints.
• Testable. The business rules can be tested without the UI, Database, Web Server, or any other external element.
• Independent of UI. The UI can change easily, without changing the rest of the system. A Web UI could be replaced with a console UI, for example, without changing the business rules.
• Independent of Database. You can swap out Oracle or SQL Server, for Mongo, BigTable, CouchDB, or something else. Your business rules are not bound to the database.
• Independent of any external agency. In fact your business rules simply don’t know anything at all about the outside world.

The diagram from the article also shows the different layers of the clean architecture and the dependencies between them:

There is another diagram from go-clean-arch by bxcodec which is more intuitive for me:

Based on the concept of clean architecture, this project contains the following layers:

• Core layer (/core): The entities layer, which contains the core business rules and logic
• Service layer (/service): The use cases layer, which contains the application of business rules and logic
• Repository layer (/repository): The infrastructure layer, which contains the data access logic
• API layer (/api): The presentation layer, which contains the HTTP API endpoints

Getting Started

Setup Environment Variables

First, setup the environment variables, please refer to the .env.example file. Ask your team for the values. You can create a new .env file by running the following command:

cp .env.example .env

Quick Start with Docker Compose

You can quickly start the server with docker compose:

docker compose -f docker-compose.yml up --remove-orphans -d

Database Setup

In this example, we use PostgreSQL as the database, please make sure you have it installed locally, you can set the DATABASE_URL in the .env file to connect to your local database:

DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/python_clean_arch

Or you can use docker compose file we provided to quickly setup one:

docker compose -f docker-compose.db.yml up --remove-orphans -d

You can change the POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD in the .env file to change the database info of docker container.

Please remember to align the DATABASE_URL with the POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD in the .env file.

After the database is running, you can initialize the database by running the following commands:

make init-db

Start the Server

With uv

uv is used to manage the dependencies and virtual environment, make sure you have it installed before you start.

1. Install dependencies

   uv sync

2. Run the server

   make run

With VSCode Debugger

VSCode is recommended for development, before you start, make sure you have installed the Python and Python Debugger extensions.

1. First, you need to install the dependencies, see With uv

2. Then, select the correct python interpreter in VSCode by press cmd + shift + p and search Python: Select Interpreter. The python interpreter should be the one you installed in the first step, usually you can find the uv-managed virtual environment in the list.

3. Then, you need to set up the debugger configuration for VSCode:

   cp .vscode/launch.example.json .vscode/launch.json

4. Choose the "FastAPI" configuration from the VSCode and run it.

Running Tests

With uv in Command Line

Make sure you have installed the dependencies with uv:

uv sync

Then, you can run the unit tests by the following command:

make run-unit-tests

With Docker

You can also run the unit tests with docker:

docker build -f Dockerfile.dev -t app-test --build-arg RUN_MODE=test . && docker run app-test

API Documentation

Once the server is running, visit the Swagger UI at http://localhost:7086/docs

Editor Integration

• Language Server - Pylance, which depends on Pyright.

• Linting and Formatting - Ruff

For VSCode, run the following command to setup the editor config:

cp .vscode/settings.example.json .vscode/settings.json