python-fastapi-ddd-skill skill
✓ VerifiedGuides backend design using Domain-Driven Design and Onion Architecture in Python with FastAPI and SQLAlchemy.
- GitHub stars
- 5
- Files
- 7
- Last commit
- Oct 24, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the python-fastapi-ddd-skill skill do?
python-fastapi-ddd-skill guides backend design using Domain-Driven Design and Onion Architecture in Python with FastAPI and SQLAlchemy.
Summary generated from the skill's SKILL.md.
About the python-fastapi-ddd-skill skill
Structuring complex FastAPI backends using Domain-Driven Design and Onion Architecture is what this skill enables. It provides a blueprint for developers building scalable Python applications by enforcing a strict separation between business logic and external frameworks. An agent should load this skill when a developer needs to organize a project into concentric layers, ensuring that the core domain remains independent of tools like SQLAlchemy or FastAPI.
The skill guides the creation of specific components including domain entities, immutable value objects, and repository interfaces. It assists in implementing the infrastructure layer with SQLAlchemy models and DTOs, while also defining the use case layer where application workflows reside. By following the provided directory structure and dependency injection patterns using FastAPI's Depends, developers can produce a clean codebase where dependencies only point inward toward the domain.
What an agent can do with it
- 1Implement repository patternsDefine abstract repository interfaces in the domain and provide concrete SQLAlchemy implementations in the infrastructure layer.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the python-fastapi-ddd-skill skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the python-fastapi-ddd-skill skill in Plugin
/plugin marketplace add iktakahiro/python-fastapi-ddd-skill /plugin install python-fastapi-ddd@python-fastapi-ddd-skills
Install the python-fastapi-ddd-skill skill in Claude Code
~/.claude/skills/python-fastapi-ddd-skill/SKILL.md
$ npx degit iktakahiro/python-fastapi-ddd-skill/skills/python-fastapi-ddd-skill ~/.claude/skills/python-fastapi-ddd-skillInstall the python-fastapi-ddd-skill skill in Claude Code (project)
.claude/skills/python-fastapi-ddd-skill/SKILL.md
$ npx degit iktakahiro/python-fastapi-ddd-skill/skills/python-fastapi-ddd-skill .claude/skills/python-fastapi-ddd-skillInstall the python-fastapi-ddd-skill skill in Codex
~/.agents/skills/python-fastapi-ddd-skill/SKILL.md
$ npx degit iktakahiro/python-fastapi-ddd-skill/skills/python-fastapi-ddd-skill ~/.agents/skills/python-fastapi-ddd-skillInstall the python-fastapi-ddd-skill skill in Gemini CLI
~/.gemini/skills/python-fastapi-ddd-skill/SKILL.md
$ npx degit iktakahiro/python-fastapi-ddd-skill/skills/python-fastapi-ddd-skill ~/.gemini/skills/python-fastapi-ddd-skillInstall the python-fastapi-ddd-skill skill in Claude.ai
npx degit iktakahiro/python-fastapi-ddd-skill/skills/python-fastapi-ddd-skill python-fastapi-ddd-skill && zip -r python-fastapi-ddd-skill.zip python-fastapi-ddd-skill # claude.ai → Customize → Skills → + → Create skill → Upload a skill → python-fastapi-ddd-skill.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachableiktakahiro/python-fastapi-ddd-skill/skills/python-fastapi-ddd-skill is public and reachablegithub.com/iktakahiro/python-fastapi-ddd-skill/tree/HEAD/ski ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-24github.com/iktakahiro/python-fastapi-ddd-skill/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/iktakahiro/python-fastapi-ddd-skill/blob/HEAD/ski ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/iktakahiro/python-fastapi-ddd-skill/blob/HEAD/ski ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 164 linesgithub.com/iktakahiro/python-fastapi-ddd-skill/blob/HEAD/ski ↗Pass
SKILL.md
View on GitHubFastAPI + Python DDD & Onion Architecture Design Guide
Guides FastAPI backend design using DDD principles and Onion Architecture, based on the dddpy reference implementation (FastAPI + SQLAlchemy + Python 3.13+).
Architecture Overview
Four concentric layers with dependencies pointing inward:
Presentation → UseCase → Infrastructure → Domain (innermost)
Key rule: Inner layers never depend on outer layers. The Domain layer has zero external dependencies.
| Layer | Responsibility | Examples |
|---|---|---|
| Domain | Core business logic, no framework deps | Entities, Value Objects, Repository interfaces, Exceptions |
| Infrastructure | External integrations | DB repos, DTOs, DI config, SQLAlchemy models |
| UseCase | Application workflows | One class per use case with execute() |
| Presentation | HTTP API surface | FastAPI routes, Pydantic schemas, error messages |
For detailed architecture guide: See ARCHITECTURE.md
Directory Structure
project/
├── main.py
├── app/
│ ├── domain/
│ │ └── {aggregate}/
│ │ ├── entities/
│ │ ├── value_objects/
│ │ ├── repositories/
│ │ └── exceptions/
│ ├── infrastructure/
│ │ ├── di/
│ │ │ └── injection.py
│ │ └── sqlite/
│ │ └── {aggregate}/
│ │ ├── {aggregate}_dto.py
│ │ └── {aggregate}_repository.py
│ ├── usecase/
│ │ └── {aggregate}/
│ │ └── {action}_{aggregate}_usecase.py
│ └── presentation/
│ └── api/
│ └── {aggregate}/
│ ├── handlers/
│ ├── schemas/
│ └── error_messages/
└── tests/
Quick Reference
1. Entity
Entities have unique identifiers, mutable state, and encapsulated business logic. Equality is based on identity, not attribute values.
class Todo:
def __init__(self, id: TodoId, title: TodoTitle, status: TodoStatus = TodoStatus.NOT_STARTED):
self._id = id
self._title = title
self._status = status
def __eq__(self, obj: object) -> bool:
if isinstance(obj, Todo):
return self.id == obj.id
return False
def start(self) -> None:
self._status = TodoStatus.IN_PROGRESS
@staticmethod
def create(title: TodoTitle) -> "Todo":
return Todo(TodoId.generate(), title)
Detailed guide: See ENTITIES.md
2. Value Object
Immutable objects defined by their values, not identity. Use @dataclass(frozen=True) with validation in __post_init__.
@dataclass(frozen=True)
class TodoTitle:
value: str
def __post_init__(self):
if not self.value:
raise ValueError("Title is required")
if len(self.value) > 100:
raise ValueError("Title must be 100 characters or less")
Detailed guide: See VALUE_OBJECTS.md
3. Repository Interface
Define abstract interfaces in the Domain layer. Infrastructure implements them.
class TodoRepository(ABC):
@abstractmethod
def save(self, todo: Todo) -> None: ...
@abstractmethod
def find_by_id(self, todo_id: TodoId) -> Optional[Todo]: ...
@abstractmethod
def find_all(self) -> List[Todo]: ...
@abstractmethod
def delete(self, todo_id: TodoId) -> None: ...
Detailed guide: See REPOSITORIES.md
4. UseCase
One class per use case. Abstract interface + concrete implementation + factory function.
class CreateTodoUseCase(ABC):
@abstractmethod
def execute(self, title: TodoTitle) -> Todo: ...
class CreateTodoUseCaseImpl(CreateTodoUseCase):
def __init__(self, todo_repository: TodoRepository):
self.todo_repository = todo_repository
def execute(self, title: TodoTitle) -> Todo:
todo = Todo.create(title=title)
self.todo_repository.save(todo)
return todo
def new_create_todo_usecase(repo: TodoRepository) -> CreateTodoUseCase:
return CreateTodoUseCaseImpl(repo)
Detailed guide: See USECASES.md
Best Practices
- Keep Domain Layer Pure: No framework imports (no FastAPI, no SQLAlchemy) in domain code
- Use DTOs at Layer Boundaries: Convert between domain entities and infrastructure models via
to_entity()/from_entity()methods - Dependency Injection: Use FastAPI's
Depends()to wire session → repository → usecase → handler - One UseCase = One Responsibility: Each UseCase has exactly one public
executemethod - Validate in Value Objects: Business rules live in
__post_init__of frozen dataclasses - Domain Exceptions: Create specific exception classes for business rule violations (e.g.,
TodoNotFoundError,TodoAlreadyCompletedError) - Factory Functions: Expose
new_*factory functions for creating implementations, keeping concrete classes as implementation details
Files in this skill
7python-fastapi-ddd-skill skill questions
How do I install the python-fastapi-ddd-skill skill in Claude Code?
Run npx degit iktakahiro/python-fastapi-ddd-skill/skills/python-fastapi-ddd-skill ~/.claude/skills/python-fastapi-ddd-skill. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the python-fastapi-ddd-skill skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What are the layers in this architecture?
The architecture consists of four concentric layers: Presentation, UseCase, Infrastructure, and Domain, where dependencies always point inward.
What is the difference between an Entity and a Value Object?
Entities have unique identifiers and mutable state with equality based on identity, while Value Objects are immutable and defined by their values.