アプリケーションを開発していると、いつの間にかコードがごちゃごちゃになっている、なんて経験はありませんか？
ビジネスロジックやデータベース、外部サービスへの接続コードが一箇所に混ざり合い、変更を加えるたびに「あれ、どこを直せばいいんだっけ？」と戸惑う――こんな状況は、多くの開発者が通る道です。

ここで頼りになるのが、ドメイン駆動開発(DDD)とクリーンアーキテクチャの考え方です。どちらも「重要なビジネスロジックを明確にし、外部の技術的要素から切り離す」ことを目指しており、その組み合わせはコードベースの見通しを劇的に改善します。本記事では、これらの考え方をふまえたPythonプロジェクトのフォルダ構成例を紹介します。

「次の機能追加はどうレイヤーに分けよう？」「DBを変えてもビジネスロジックに影響が出ないようにしたい」――そんなときに立ち戻れる、一つの指針として参考にしてください。

なぜDDDとクリーンアーキテクチャを組み合わせるのか？

DDD (ドメイン駆動開発)：ソフトウェアの「本当に重要な部分」、すなわちビジネスロジック（ドメイン）を中心に据え、チームが理解しやすいモデルとして定義していく手法です。
クリーンアーキテクチャ：コアのロジックを外部技術から独立させ、依存関係を内側から外側へ一方向に保ちます。これにより、UI、DB、フレームワークなどを取り替えても、ビジネスロジックが簡単には揺らぎません。

両者を組み合わせることで、ドメインモデルを中心とした明確な構造をつくりやすくなります。ドメインをしっかり定義し、その周囲にアプリケーション層、インフラ層、インターフェース層を配していくことで、どこに何を書くべきかが自然に決まってきます。

Pythonプロジェクトの基本スタイル

最近のPythonプロジェクトでは、src/ 配下にコードをまとめ、pyproject.tomlで依存管理をするパターンがよく使われます。PoetryやPipenvとの相性も良く、CI/CDパイプライン構築もやりやすいのがメリットです。

ここで紹介する分割は大きく4つのレイヤーです。

domain：ビジネスロジックの本体（エンティティ、値オブジェクト、ドメインサービス、リポジトリの抽象インターフェース）
application：ユースケース（ビジネスロジックを活用して、アプリケーションとしての操作・振る舞いを定義）
infrastructure：DBや外部APIアクセスなど、環境依存の実装部分
interface：WebフレームワークやCLIなど、ユーザーや外部からの入力・出力部分

フォルダ構成例

以下は一つの参考例です。プロジェクト規模や要件に合わせてアレンジできますが、この構成を押さえておくと迷いにくくなります。

project_name/
├─ pyproject.toml
├─ README.md
├─ docs/
├─ tests/
└─ src/
    ├─ domain/
    │   ├─ entities/
    │   │   ├─ user.py
    │   │   └─ order.py
    │   ├─ value_objects/
    │   │   └─ email_address.py
    │   ├─ services/
    │   │   └─ order_service.py
    │   └─ repositories/
    │       └─ user_repository.py   # 抽象インターフェースのみ定義
    │
    ├─ application/
    │   ├─ use_cases/
    │   │   ├─ create_user.py
    │   │   ├─ get_user.py
    │   │   └─ update_order.py
    │   ├─ dtos/
    │   │   └─ user_dto.py
    │   └─ interfaces/
    │       └─ user_repository_if.py # domainの抽象Repoを参照
    │
    ├─ infrastructure/
    │   ├─ persistence/
    │   │   ├─ orm_user.py     # DB接続によるUserRepo実装
    │   │   └─ db_config.py
    │   ├─ external_services/
    │   │   └─ payment_gateway.py
    │   └─ config/
    │       └─ settings.py
    │
    └─ interface/
        ├─ web/
        │   ├─ fastapi_app.py
        │   ├─ routes.py
        │   └─ controllers/
        │       └─ user_controller.py
        ├─ cli/
        │   └─ cli_commands.py
        └─ presenters/
            └─ user_presenter.py

各ディレクトリの役割

domain/：ビジネスモデルが純度100%で存在する場所。外部には依存せず、エンティティや値オブジェクトを定義します。
application/：ユースケース単位でビジネスロジックを呼び出す層。domainには依存しますが、infrastructureやinterfaceには直接依存しないようにします。
infrastructure/：具体的なDBアクセスや外部サービスへの接続処理など、技術的な詳細を実装する層です。
interface/：Web APIやCLIなど、外部からアプリケーションを操作する際の入り口。コントローラやルーティング、プレゼンテーション周りの処理をまとめます。

依存関係の流れ

クリーンアーキテクチャでは、ドメインが一番内側に位置します。

domainはどこにも依存しない
applicationはdomainへ依存するが、infrastructureやinterfaceには依存しない（抽象経由で接続）
infrastructureとinterfaceはapplicationやdomainの抽象を実装し、外側から内側を参照しない

こうすることで、たとえばDBを変えたくなったときでもdomainやapplicationには手を入れず、infrastructure側だけで対応できます。テスト時にはMockリポジトリを簡単に差し替えることも容易です。

簡単な例：UserエンティティとUseCase

domain層

# src/domain/entities/user.py
class User:
    def __init__(self, user_id: str, email: "EmailAddress"):
        self.user_id = user_id
        self.email = email

# src/domain/value_objects/email_address.py
class EmailAddress:
    def __init__(self, value: str):
        # メール形式の簡易チェックなど
        self.value = value

# src/domain/repositories/user_repository.py
from abc import ABC, abstractmethod
from domain.entities.user import User

class UserRepository(ABC):
    @abstractmethod
    def find_by_id(self, user_id: str) -> User:
        pass

    @abstractmethod
    def save(self, user: User) -> None:
        pass

application層

# src/application/use_cases/create_user.py
from domain.repositories.user_repository import UserRepository
from domain.value_objects.email_address import EmailAddress
from domain.entities.user import User

class CreateUserUseCase:
    def __init__(self, user_repo: UserRepository):
        self.user_repo = user_repo

    def execute(self, user_id: str, email_str: str):
        email = EmailAddress(email_str)
        user = User(user_id, email)
        self.user_repo.save(user)

infrastructure層（DB実装例）

# src/infrastructure/persistence/orm_user.py
from domain.repositories.user_repository import UserRepository
from domain.entities.user import User

class ORMUserRepository(UserRepository):
    def find_by_id(self, user_id: str) -> User:
        # DB検索処理（ORMによる実装）
        ...

    def save(self, user: User) -> None:
        # DBへINSERT/UPDATE
        ...

interface層（Webエンドポイント例）

# src/interface/web/user_controller.py
from fastapi import APIRouter
from application.use_cases.create_user import CreateUserUseCase
from infrastructure.persistence.orm_user import ORMUserRepository

router = APIRouter()

@router.post("/users")
def create_user(user_id: str, email: str):
    uc = CreateUserUseCase(ORMUserRepository())
    uc.execute(user_id, email)
    return {"status": "ok"}

このようにドメインやアプリケーション層では具体的なORMやWebフレームワークに依存していないため、外側の技術を置き換えるのも比較的容易です。

まとめ

DDDでビジネスロジック（ドメイン）をしっかり定義
クリーンアーキテクチャで依存関係を整理してテストしやすいコード構成へ
Pythonで src/ 以下にレイヤー分割すると、変更容易性・保守性が大幅に向上

この構成を導入すれば、「またDBを変えるの？」「フレームワークをアップデートするの面倒だな」といった局面でも、コアなビジネスロジックは手を加えずに済むはずです。日々の開発で悩むことが少しでも減り、あなたのチームがよりスムーズにプロダクトを成長させていくためのヒントになれば幸いです。