reference clean architecture

    1

    Implement Clean Architecture and hexagonal patterns to decouple business logic from frameworks and databases.

    Free

    Security scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+22 more

    reference clean architecture

    Example session with this skill installed

    I have a fat FastAPI router handling user registration, DB commits, and email sending. Help me refactor this into Clean Architecture layers.

    • Read your context and instructions
    • Compiled the reference clean architecture

    I will refactor the user registration logic by separating the HTTP concerns from the business rules and database persistence.

    User Registration Refactor

    LayerFile / ComponentResponsibility
    Entitydomain/user.pyPure Python dataclass for User with password validation logic. No ORM.
    Repositoryinfra/user_repo.pyUserRepository interface and SqlUserRepository implementation using SQLAlchemy.
    Use Caseapp/register_user.pyOrchestrates the flow: check existing, hash password, save via UoW, trigger email.
    Adapterapi/v1/auth.pyFastAPI router that validates UserRegisterRequest and calls the use case.
    
# use_cases/register_user.py
from dataclasses import dataclass
from domain.user import User
from infra.unit_of_work import UnitOfWork

def register_user_use_case(uow: UnitOfWork, email: str, raw_password: str) -> User:
    with uow:
        if uow.users.get_by_email(email):
            raise UserAlreadyExistsError(email)
        
        user = User.create(email=email, password=raw_password)
        uow.users.save(user)
        # Transaction commits here on successful exit
        return user

    Next steps

    1. Define the UserRepository Protocol/Interface to keep the Use Case decoupled from SQLAlchemy.
    2. Implement the UnitOfWork context manager to wrap the db.session lifecycle.
    3. Configure import-linter in your .importlinter file to prevent domain from importing infra.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    When backend services grow, they often collapse into "fat controllers" and spaghetti logic that is impossible to test or refactor. This skill provides a strict blueprint for implementing Clean Architecture, hexagonal design, and ports-and-adapters patterns to decouple business logic from frameworks and databases.

    What it does

    • Enforce Layering Rules by defining strict dependency directions between Entities, Use Cases, Repositories, and Adapters.
    • Implement Unit of Work patterns to manage database transactions at the use-case boundary rather than the repository level.
    • Design Boundary Enforcement strategies using stack-specific tools like import-linter, ArchUnit, or eslint-plugin-boundaries to prevent architectural drift.
    • Scaffold New Services with consistent naming conventions and directory structures for Python, TypeScript, Java, and Go.
    • Migrate Legacy Code using the strangler-fig pattern to incrementally move logic out of monolithic files without risky rewrites.

    How it works

    1. Layer Assignment starts by placing every new or existing file into one of the four architectural layers based on its imports and responsibilities.
    2. Boundary Tooling setup involves configuring automated CI checks that fail if an inner layer (like an Entity) attempts to import an outer layer (like an ORM).
    3. Transaction Mapping moves commit logic from repositories to a Unit of Work context manager called by the Use Case.
    4. Consistency Audit verifies that naming conventions for Entities, Repositories, and DTOs match the domain model.

    Frameworks & tools

    Language-agnostic logic with specific implementation guides for Python (FastAPI, SQLAlchemy), TypeScript (NestJS, TypeORM), Java (Spring Boot), and Go. Uses import-linter, dependency-cruiser, and ArchUnit for automated enforcement.

    Why this beats prompting it yourself

    Most LLMs default to "active record" patterns and "fat controllers" because that is what appears most in public training data. This skill forces a professional, decoupled architecture that stays maintainable as the project scales, preventing the common trap of leaking database details into business rules.

    Use cases

    • Decoupling a core business engine from a specific framework like FastAPI or Express.
    • Adding a CLI or Cron entry point to a service that was originally built only for HTTP.
    • Breaking down a 2000-line "fat router" file into testable, single-purpose use cases.
    • Establishing architectural standards for a new monorepo that multiple teams will contribute to.

    Known limitations

    Not suitable for small scripts, single-file CLI utilities, or throwaway prototypes where layering overhead exceeds the benefits. Requires manual configuration of third-party linter tools in CI.

    How to use

    Skills on Agensi run inside your AI agent. Copy the prompt, paste it into your agent, and it connects to Agensi and installs this skill for you. If a payment is needed, your agent shows it to you first.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill passes our trust checks below.

    Security scanned

    Passed our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Free forever

    No account required to browse

    Trust & safety

    Security scanned

    Verified clean today

    • Free to download with an account

    Listedtoday

    What's inside

    Frequently Asked Questions