Payment Methods

• Credit card processing through Stripe
• Bank transfer support
• Multiple currency handling
• Automatic invoice generation

Production Readiness

BaseAPI is designed for production deployment with enterprise-grade features:

• Docker Support: Container-ready for Kubernetes deployment
• Environment Configuration: Separate configs for development, staging, and production
• Database Migrations: Version-controlled schema changes with Alembic
• Error Handling: Comprehensive error handling and logging
• Security: JWT authentication, CORS configuration, and input validation

Why Choose BaseAPI?

Traditional API development can take weeks or months to set up properly. BaseAPI eliminates this overhead by providing:

• Instant Development: Start building features immediately, not infrastructure
• Battle-Tested Components: All integrations are production-ready and thoroughly tested
• Scalable Architecture: Modular design supports teams and complex applications
• Complete Feature Set: Authentication, payments, background jobs, and email—all included
• Developer Experience: Automatic API documentation, type hints, and modern Python practices

Table of contents

1. Overview
2. Architecture Principles
   1. Introduction
   2. Layered Approach
   3. Dependency Rule
      1. Note on Adapters
   4. Layered Approach Continued
   5. Dependency Inversion
   6. Dependency Injection
   7. CQRS
3. Project
   1. Dependency Graphs
   2. Structure
   3. Technology Stack
   4. API
      1. General
      2. Account
      3. Users
   5. Configuration
      1. Files
      2. Flow
      3. Local Environment
      4. Other Environments
      5. Adding New Environments
4. BaseAPI Integration
   1. What is BaseAPI?
   2. Core Features
   3. Business Model Support
   4. Production Readiness
   5. Why Choose BaseAPI?
5. Useful Resources
6. Support the Project
7. Acknowledgements

Architecture Principles

Introduction

This repository may be helpful for those seeking a backend implementation in Python that is both framework-agnostic and storage-agnostic (unlike Django). Such flexibility can be achieved by using a web framework that doesn't impose strict software design (like FastAPI) and applying a layered architecture patterned after the one proposed by Matias Baglieri, which we'll explore further.

The most abstract policies define core business rules, while the least abstract ones handle I/O operations. Being closer to implementation details, less abstract policies are more likely to change. A layer represents a collection of components expressing policies at the same level of abstraction.

The concentric circles represent boundaries between different layers. The meaning of the arrows in the diagram will be discussed later. For now, we will focus on the purpose of the layers.

Layered Approach

Domain Layer

• The core of the application, containing entities, value objects, and domain services that encapsulate critical business rules — fundamental principles or constraints that define how the business operates and delivers value. In some cases, these rules can be seen as mechanisms that create the product's value independently of its software implementation. Changing them often reflects a change in the business itself.
• It establishes a ubiquitous language — a consistent terminology shared across the application and domain. This is the language you can speak with managers.
• It's the most stable and independent part of the application.
• Domain services originally represent operations that don't naturally belong to a specific entity. In projects with anemic domain models — where entities hold data but no behavior — domain services may also include logic that would otherwise reside inside those entities.

[!NOTE] The Domain layer may also include aggregates (groups of entities that must change together as a single unit, defining the boundaries of transactional consistency) and repository interfaces (abstractions for manipulating aggregates). While these concepts aren't implemented in the project's codebase, understanding them can deepen your knowledge of DDD.

Application Layer

• This layer implements the application-specific business logic by realizing steps of business-defined use cases.
• Its main components are interactors — each handles a single business operation matching a step within a use case.
• An interactor orchestrates domain logic and external calls needed to perform the operation.
• Interactors are stateless, isolated, and do not call each other. Each is invoked independently — typically by external drivers such as HTTP controllers, message consumers, or scheduled jobs.
• To access external systems, interactors rely on interfaces (ports) that abstract infrastructure details.
• In some cases, application services may group related interactors under a common business context.
• The layer may also include standalone services for non-orchestration logic, such as authorization.

[!NOTE] Domain and Application layers may import external tools and libraries to the extent necessary for describing business logic — such as utilities for numerical computations, timezone management, or object modeling that extend the language's capabilities. However, they should avoid any ties to specific frameworks, databases, or external systems.

Infrastructure Layer

• This layer is responsible for adapting the application to external systems.
• It provides implementations (adapters) for the interfaces (ports) defined in the Application layer, allowing the application to interact with external systems like databases, APIs, and file systems while keeping the business logic decoupled from them.
• Related adapter logic can be grouped into an infrastructure service.

[!IMPORTANT]

• Clean Architecture doesn't prescribe any particular number of layers. The key is to follow the Dependency Rule, which is explained in the next section.

Dependency Rule

A dependency occurs when one software component relies on another to operate. If you were to split all blocks of code into separate modules, dependencies would manifest as imports between those modules. Typically, dependencies are graphically depicted in UML style in such a way that

[!IMPORTANT]

• A -> B (A points to B) means A depends on B.

The key principle of Clean Architecture is the Dependency Rule. This rule states that more abstract software components must not depend on more concrete ones. In other words, dependencies must never point outwards within the application's boundaries.

[!IMPORTANT]

• Components within the same layer can depend on each other. For example, components in the Infrastructure layer can interact with one another without crossing into other layers.

• Components in any outer layer can depend on components in any inner layer, not necessarily the one closest to them. For example, components in the Presentation layer can directly depend on the Domain layer, bypassing the Application and Infrastructure layers.

• Avoid letting business logic leak into peripheral details, such as raising business-specific exceptions in the Infrastructure layer without re-raising them in the business logic or declaring domain rules outside the Domain layer.

• In specific cases where database constraints enforce business rules, the Infrastructure layer may raise domain-specific exceptions, such as emailAlreadyExistsError for a UNIQUE CONSTRAINT violation. Handling these exceptions in the Application layer ensures that any business logic implemented in adapters remains under control.

• Avoid introducing elements in inner layers that specifically exist to support outer layers. For example, you might be tempted to place something in the Application layer that exists solely to support a specific piece of infrastructure. At first glance, based on imports, it might seem that the Dependency Rule isn't violated. However, in reality, you've broken the core idea of the rule by embedding infrastructure concerns (more concrete) into the business logic (more abstract).

Note on Adapters

The Infrastructure layer in the Clean Architecture acts as the adapter layer — connecting the application to external systems. In this project, we treat both Infrastructure and Presentation as adapters, since both adapt the application to the outside world. Speaking of dependencies direction, the diagram by R. Martin in Figure 1 can, without significant loss, be replaced by a more concise and pragmatic one — where