datamktkorea/agent-skills

Overview

This skill guides developers to apply FastAPI best practices with Domain-Driven Design (DDD) and Hexagonal Architecture. It prescribes a clear project layout, layer responsibilities, and dependency rules to produce maintainable, testable, and scalable applications. Use it as a practical checklist for architecture, DI strategy, error handling, and testing.

How this skill works

The skill inspects and enforces patterns across layers: interface (controllers/schemas), application (services/use-cases), domain (entities, interfaces, exceptions), and infrastructure (ORM models, repository implementations). It recommends one DI strategy per project, centralizes exception handling, and defines mapping responsibilities between ORM models, domain entities, and Pydantic schemas. The guidance also defines testing strategies and pragmatic trade-offs for mapping complexity.

When to use it

• Starting a new FastAPI service that needs long-term maintainability
• Refactoring a monolithic FastAPI app into clear layers
• Onboarding teams to a standardized FastAPI project structure
• Choosing a dependency injection approach for small vs. medium/large projects
• Designing test strategy covering unit, integration, and E2E tests

Best practices

• Adopt a consistent project layout: app/routes per domain, application/domain/infra separation, and shared libs for DI and global handlers
• Keep domain layer framework-free: use dataclasses/value objects and domain exceptions only
• Choose one DI strategy up front: dependency-injector for medium+ projects or FastAPI native DI for small projects
• Let infrastructure implement domain ports and handle ORM ↔ entity mapping inside infra layer
• Raise domain exceptions in services; convert to HTTP responses only in controllers or global handlers
• Use AsyncMock for service unit tests, testcontainers for integration tests, and httpx.AsyncClient for async E2E tests

Example use cases

• Building a multi-domain FastAPI API (users, orders, products) with separate routers per domain
• Implementing repository interfaces and multiple DB implementations without leaking ORM into domain code
• Setting up centralized exception handlers that map domain errors to HTTP status codes
• Scaling a small app by switching from native DI to dependency-injector when domains grow
• Reducing mapping complexity by choosing pragmatic Pydantic-based domain models when agreed by the team