- Home
- Skills
- APIs & Backend
- reference clean architecture
reference clean architecture
Implement Clean Architecture and hexagonal patterns to decouple business logic from frameworks and databases.
Free
Works with the AI Agents you already use
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
| Layer | File / Component | Responsibility |
|---|---|---|
| Entity | domain/user.py | Pure Python dataclass for User with password validation logic. No ORM. |
| Repository | infra/user_repo.py | UserRepository interface and SqlUserRepository implementation using SQLAlchemy. |
| Use Case | app/register_user.py | Orchestrates the flow: check existing, hash password, save via UoW, trigger email. |
| Adapter | api/v1/auth.py | FastAPI 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
- Define the
UserRepositoryProtocol/Interface to keep the Use Case decoupled from SQLAlchemy. - Implement the
UnitOfWorkcontext manager to wrap thedb.sessionlifecycle. - Configure
import-linterin your.importlinterfile to preventdomainfrom importinginfra.
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
- Layer Assignment starts by placing every new or existing file into one of the four architectural layers based on its imports and responsibilities.
- 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).
- Transaction Mapping moves commit logic from repositories to a Unit of Work context manager called by the Use Case.
- 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.
Not for small scripts or prototypes. Requires configuring external tools like import-linter or ArchUnit in CI. Does not support pure frontend/UI architecture.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
2 uses
Times used to date
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 28 days ago
- Free with an Agensi account