Python fastapi ddd presentation skill

Skill iktakahiro/python-fastapi-ddd-skill/skills/python-fastapi-ddd-presentation-skill

A practical template for Building AI Agent Skills with Python, FastAPI, and Domain-Driven Design (DDD).

Install

npx -y skills add iktakahiro/python-fastapi-ddd-skill --skill python-fastapi-ddd-presentation-skill

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Guides the FastAPI Presentation layer in a Python DDD + Onion Architecture app (route handler structure, Pydantic request/response schemas, mapping Domain exceptions to HTTP errors, and OpenAPI error documentation), based on the dddpy reference. Use when adding/refactoring endpoints that call UseCases and convert primitives ↔ Value Objects/Entities.

The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.0 KB, as published. Nobody here has run it

FastAPI Presentation Layer (DDD / Onion Architecture)

This skill focuses on the Presentation layer only: FastAPI routes/handlers, Pydantic schemas, and HTTP error mapping. It assumes you already have Domain + UseCase layers and repository wiring.

Non-negotiables (Onion rule)

Presentation is the outermost layer: it can depend on UseCase and Domain types, but Domain must not depend on FastAPI/Pydantic.
Keep business rules inside Domain/UseCase. Presentation does:
- request parsing/validation (shape, basic constraints)
- conversion primitives → Value Objects
- calling usecase.execute(...)
- mapping Domain exceptions → HTTPException
- conversion Entity → response schema

Recommended structure (per aggregate)

presentation/
  api/
    {aggregate}/
      handlers/
      schemas/
      error_messages/

Implementation checklist (per endpoint)

Depend on UseCase interface via Depends(get_*_usecase).
Convert inputs (UUID, str, etc.) into Domain Value Objects.
Handle ValueError (from Value Objects) as 400 Bad Request.
Execute the use case.
Map Domain exceptions (e.g., NotFound, lifecycle errors) to 404/400.
Return response model using Schema.from_entity(entity) (or equivalent).
Document errors in OpenAPI using responses={...: {'model': ...}}.

Route handler pattern (based on dddpy)

Prefer a small “route registrar” class per aggregate.

class TodoApiRouteHandler:
    def register_routes(self, app: FastAPI):
        @app.post("/todos", response_model=TodoSchema, status_code=201)
        def create_todo(
            data: TodoCreateSchema,
            usecase: CreateTodoUseCase = Depends(get_create_todo_usecase),
        ):
            try:
                title = TodoTitle(data.title)
                description = (
                    TodoDescription(data.description) if data.description else None
                )
            except ValueError as e:
                raise HTTPException(status_code=400, detail=str(e)) from e

            todo = usecase.execute(title, description)
            return TodoSchema.from_entity(todo)

Pydantic schemas

Request schemas: validate shape + basic constraints (min/max length, optional fields).
Response schemas: provide from_entity() to convert Domain types (UUID/datetime) into JSON-friendly primitives (e.g., timestamps as milliseconds).

For detailed templates and a fuller walk-through, read references/PRESENTATION.md.