YankielDBC2 Backend Clean Architecture
Goal
Produce backend code that is small, testable, reusable, and easy to reason about. Keep orchestration at the edges and business behavior in focused modules.
When to use
Use for backend features, API routes, controllers, services, database logic, auth, validation, error handling, and backend refactors.
When not to use
Do not use for frontend-only UI work, copywriting, visual design, or unrelated project management tasks.
Read first
- The affected route/controller/handler.
- Direct service/use-case imports.
- Existing validator/schema/error helpers.
- Database model/repository only if persistence changes.
- Related tests if behavior changes.
Do not scan the whole backend unless the task requires an architecture review.
Workflow
- Identify the real owner of the behavior.
- Keep request parsing and response formatting in routes/controllers.
- Put business logic in services or use-cases.
- Put persistence in repositories or query modules.
- Reuse validation, auth, mapping, and error helpers.
- Preserve public behavior unless the user asked for a behavior change.
- Add regression coverage at the smallest meaningful seam.
- Delete obsolete paths when safe.
Architecture rules
- Routes/controllers parse request, call service/use-case, return response.
- Services/use-cases own business logic.
- Repositories/query modules own data access.
- Validators/schemas own input validation.
- Error helpers own normalized error responses.
- Auth/session helpers own identity and permission checks.
- External API calls live behind clients/adapters.
- Do not introduce hidden global state.
Validation
Run available relevant commands: typecheck, lint, unit tests for affected modules, integration tests for changed endpoints, and build when meaningful.
Final response
Report changed files, architecture decisions, validation output, and any known risks.