Clean Codebase Architecture Playbook
This skill instructs the agent to systematically refactor monolithic, coupled, or chaotic backend code into a structured, scalable design.
Target Triggers
/improve-codebase-architecture"refactor to clean architecture""clean controller service repository"
Design Standards
To prevent context bloat and ensure separation of concerns, the backend code should follow the standard layer separation:
1. Controllers (Routing / Transport Layer)
- Handles HTTP requests, parses query/body params, manages status codes, and responds (JSON/HTML).
- Rule: Controllers must NOT execute database operations or complex business logic. They should only validate input shapes (e.g. using Pydantic, Zod, or Joi) and delegate to services.
2. Services (Business Logic Layer)
- Orqestrates domain logic, workflows, external APIs (payment gates, search clients), and coordinates repositories.
- Rule: Services must be transport-agnostic (should not know about
req, res, HttpExchange, or specific route details). They should receive native data types/DTOs.
3. Repositories / DAOs (Data Access Layer)
- Directly interacts with database APIs, ORMs (Prisma, EF Core, SQLAlchemy, Hibernate), or cache layers.
- Rule: Repositories must NOT execute business rules. They only query and persist data.
Step-by-Step Refactoring Process
- Audit current files: Map out the controllers/endpoints that have bloated business logic or raw inline database calls.
- Define Data Transfer Objects (DTOs): Determine the interfaces/schemas for data flowing between layers.
- Extract Repositories: Create repository functions or classes with clean database APIs (e.g.
UserRepository.find_by_email()).
- Extract Services: Pull out the core business operations (e.g.
AuthService.register_user()) and inject/use the repository.
- Clean the Controller: Simplify the route handler to call the service method, handle errors, and return response codes.
- Verify and Test: Re-run existing unit and integration tests to ensure logic is preserved.
1---2name: improve-codebase-architecture3description: Reorganizes backend codebases to enforce clean architectural patterns (Controllers, Services, Repositories/Data Access Objects) to reduce token bloat and maintain codebase longevity.4---5# Clean Codebase Architecture Playbook67This skill instructs the agent to systematically refactor monolithic, coupled, or chaotic backend code into a structured, scalable design.89## Target Triggers10- `/improve-codebase-architecture`11- `"refactor to clean architecture"`12- `"clean controller service repository"`1314## Design Standards1516To prevent context bloat and ensure separation of concerns, the backend code should follow the standard layer separation:1718### 1. Controllers (Routing / Transport Layer)19- Handles HTTP requests, parses query/body params, manages status codes, and responds (JSON/HTML).20- **Rule**: Controllers must NOT execute database operations or complex business logic. They should only validate input shapes (e.g. using Pydantic, Zod, or Joi) and delegate to services.2122### 2. Services (Business Logic Layer)23- Orqestrates domain logic, workflows, external APIs (payment gates, search clients), and coordinates repositories.24- **Rule**: Services must be transport-agnostic (should not know about `req`, `res`, `HttpExchange`, or specific route details). They should receive native data types/DTOs.2526### 3. Repositories / DAOs (Data Access Layer)27- Directly interacts with database APIs, ORMs (Prisma, EF Core, SQLAlchemy, Hibernate), or cache layers.28- **Rule**: Repositories must NOT execute business rules. They only query and persist data.2930## Step-by-Step Refactoring Process31321. **Audit current files**: Map out the controllers/endpoints that have bloated business logic or raw inline database calls.332. **Define Data Transfer Objects (DTOs)**: Determine the interfaces/schemas for data flowing between layers.343. **Extract Repositories**: Create repository functions or classes with clean database APIs (e.g. `UserRepository.find_by_email()`).354. **Extract Services**: Pull out the core business operations (e.g. `AuthService.register_user()`) and inject/use the repository.365. **Clean the Controller**: Simplify the route handler to call the service method, handle errors, and return response codes.376. **Verify and Test**: Re-run existing unit and integration tests to ensure logic is preserved.
AravindS-Wick