clean-architecture-ts_skill

Overview

This skill teaches applying Clean Architecture to Remix + TypeScript apps to keep loaders and actions thin. It prescribes a Web layer for request orchestration, a Service layer for business rules, and a Repository layer for data access, plus optional dependency injection and structured error handling. Followed correctly, it improves testability, maintainability, and separation of concerns.

How this skill works

Inspect your route handlers and move parsing/validation and response shaping into the Web layer only. Implement business logic inside services that are framework-agnostic and call repositories for any database or external API operations. Optionally register services and repositories in a DI container to swap implementations in tests and composition roots.

When to use it

• When route loader/action functions become long or contain business rules
• When you need clearer boundaries for testing complex flows
• When multiple routes share the same business logic
• When you integrate external APIs or multiple data sources and want a single abstraction
• When you want consistent error handling and HTTP status mapping

Best practices

• Keep Web layer limited to request parsing (Zod), auth, orchestration, and returning Responses
• Encapsulate business rules and flows in Services; never access Request/Response there
• Let Repositories be the only place that touches Prisma, HTTP clients, or the filesystem
• Use DI (e.g., tsyringe) for complex apps to inject repositories into services for easier mocking
• Define custom error classes (BusinessError, NotFoundError) and map them to HTTP codes in routes
• Organize code by layer folders: routes/, services/, repositories/, models/, utils/

Example use cases

• Updating a product: action validates input, calls ProductService.updateProduct, returns json
• Order processing: OrderService orchestrates inventory check, payment, and fulfillment repositories
• Testing: swap real Repositories for in-memory mocks via DI to run fast unit tests
• External API integration: create ShopifyClient inside repositories and keep service logic unchanged
• Incremental refactor: extract business logic from bloated loaders into services one endpoint at a time