--- description: Comprehensive guide for implementing backend modules following Clean Architecture principles, covering Domain, Application, and Infrastructure layers, along with testing strategies and best practices. name: development_workflow --- # Development Workflow Skill This skill provides a structured guide for implementing backend modules in the Pixeat project, adhering to Clean Architecture principles. It covers the creation of new modules, implementation details for each layer, testing strategies, and common pitfalls to avoid. ## 1. Module Structure Every module must follow this strict three-layer architecture: ``` src/modules/{entity}/ ├── domain/ # Entities, interfaces, business rules (framework-independent) ├── application/ # Use cases, DTOs, orchestration logic └── infra/ # Controllers, repositories, external integrations ``` ### Key Rules: - **Domain layer** has NO dependencies on other layers. - **Application layer** depends ONLY on domain. - **Infrastructure layer** depends on both but implements domain interfaces. - **Business logic** lives in use cases, NOT in controllers or repositories. --- ## 2. Domain Layer Implementation ### File: `{entity}.entity.ts` Define the entity using TypeBox schema. Ensure all fields have a `description` property. ```typescript import { type Static, t } from "elysia"; /** * Entity Name * * Brief description of what this entity represents. * * Main fields: * - field1: Description of field1 * * Business rules: * - Rule 1 */ export const EntityEntity = t.Object({ id: t.String({ format: "uuid", description: "Unique entity ID" }), restaurantId: t.String({ format: "uuid", description: "Owner restaurant ID" }), name: t.String({ minLength: 2, maxLength: 100, description: "Entity name" }), isActive: t.Boolean({ default: true, description: "Flag indicating if entity is active" }), createdAt: t.Date({ description: "Record creation timestamp" }), updatedAt: t.Nullable(t.Date({ description: "Last update timestamp" })), }); export type Entity = Static; ``` ### File: `{entity}.repository.ts` Define the repository interface (contract). ```typescript import type { Entity } from "./entity.entity"; export interface IEntityRepository { findById(id: string): Promise; create(data: Omit): Promise; update(id: string, data: Partial): Promise; delete(id: string): Promise; // HARD DELETE ONLY } ``` --- ## 3. Application Layer Implementation ### File: `{entity}.dto.ts` Define input/output DTOs for API operations. ```typescript import { type Static, t } from "elysia"; export const CreateEntityDTO = t.Object({ name: t.String({ minLength: 2, maxLength: 100 }), description: t.Optional(t.String({ maxLength: 500 })), }); export type CreateEntityInput = Static; ``` ### File: `{operation}-{entity}.use-case.ts` Implement business logic. Each operation gets its own file. ```typescript import type { SessionAuthObject } from "elysia-clerk"; import { NotFoundError } from "@/modules/shared/infra/errors"; import { requirePermission } from "@/modules/shared/infra/permissions"; import { getActiveRestaurant } from "@/modules/shared/infra/restaurant.helper"; import { EntityRepository } from "../infra/entity.repository"; // Import from infra allowed within same domain export const createEntityUseCase = async ( authContext: SessionAuthObject, data: CreateEntityInput ): Promise => { // 1. Validate active restaurant (if restaurant-scoped) const restaurant = await getActiveRestaurant(authContext); // 2. Check permissions await requirePermission(authContext, restaurant.id, "entities", "create"); // 3. Business logic validation const existing = await EntityRepository.findByName(data.name); if (existing) { throw new Error("Entity with this name already exists"); } // 4. Create entity const entity = await EntityRepository.create({ restaurantId: restaurant.id, ...data, }); return entity; }; ``` ### File: `index.ts` Centralize exports. ```typescript export { createEntityUseCase } from "./create-entity.use-case"; export { CreateEntityDTO } from "./entity.dto"; export type { CreateEntityInput } from "./entity.dto"; ``` --- ## 4. Infrastructure Layer Implementation ### File: `{entity}.repository.ts` Implement the repository using Drizzle ORM. ```typescript import { and, eq } from "drizzle-orm"; import { db } from "@/db/connection"; import { entities } from "@/db/schemas/entities"; import type { Entity } from "../domain/entity.entity"; import type { IEntityRepository } from "../domain/entity.repository"; class EntityRepositoryImpl implements IEntityRepository { async findById(id: string): Promise { const result = await db .select() .from(entities) .where(eq(entities.id, id)) .limit(1); return (result[0] as Entity) || null; } async create(data: any): Promise { const result = await db.insert(entities).values(data).returning(); return result[0] as Entity; } // Implement other methods... } export const EntityRepository = new EntityRepositoryImpl(); ``` ### File: `{entity}.controller.ts` Implement HTTP routes using Elysia. ```typescript import Elysia, { t } from "elysia"; import { authPlugin } from "@/modules/shared/infra/auth.middleware"; import { createEntityUseCase, CreateEntityDTO } from "../application"; import { EntityEntity } from "../domain/entity.entity"; export const EntityController = new Elysia({ prefix: "/entities" }) .use(authPlugin) .post( "/", async ({ auth, body }) => { return await createEntityUseCase(auth(), body); }, { body: CreateEntityDTO, response: { 200: EntityEntity, 400: t.Object({ message: t.String() }), // ... other responses }, detail: { tags: ["Entities"], summary: "Create new entity", description: "Creates a new entity in the active restaurant.", security: [{ bearerAuth: [] }], }, } ); ``` --- ## 5. Testing Strategy ### Unit Tests **Location**: `test/unit/{module}/{module}.use-cases.test.ts` **Purpose**: Test use cases with mocked dependencies. ```typescript import { describe, test, expect, beforeEach } from "bun:test"; import { setupUseCaseTest, f } from "../../helpers/test-utils"; const t = setupUseCaseTest(); describe("createEntityUseCase", () => { beforeEach(() => t.reset()); test("creates entity successfully", async () => { const restaurant = f.restaurant(); t.mock.restaurant.getActive.mockResolvedValue(restaurant); // ... setup mocks and execute use case }); }); ``` ### Integration Tests **Location**: `test/integration/repositories/{module}.repository.test.ts` **Purpose**: Test repository logic with real DB queries in transactions. ```typescript import { describe, expect, test } from "bun:test"; import { runInTestTransaction } from "../../helpers/db-transaction"; describe("EntityRepository - Integration", () => { test("creates and retrieves entity", async () => { await runInTestTransaction(async (txDb) => { // ... perform DB operations within transaction }); }); }); ``` ### E2E Tests **Location**: `test/e2e/{module}.routes.test.ts` **Purpose**: Full stack tests against real services. **Manual cleanup required.** --- ## 6. Common Pitfalls to Avoid 1. **Cross-Entity Repository Access**: - ❌ **Wrong**: Use case accessing another entity's `Repository`. - ✅ **Correct**: Use case calling another entity's `Use Case`. 2. **Clerk-Managed Fields**: - ❌ **Wrong**: Updating Clerk fields (e.g., `firstName`, `email`) directly in DB. - ✅ **Correct**: Update via `clerkClient`, let webhooks sync to DB. 3. **Permission Checks**: - ❌ **Wrong**: Skipping permission checks in use cases. - ✅ **Correct**: Always use `requirePermission`, `ensureAdmin`, or `ensureActiveOrganization`. 4. **Business Logic in Controllers**: - ❌ **Wrong**: Putting logic in controller handlers. - ✅ **Correct**: Controllers only orchestrate; logic stays in use cases. 5. **Database Access within Use Case**: - ❌ **Wrong**: Importing `db` or `drizzle-orm` in use case. - ✅ **Correct**: Use repository abstraction. --- ## 7. Workflow Checklist When creating a new feature or module, follow these steps: 1. **Domain Layer**: - [ ] Create `{entity}.entity.ts` with TypeBox schema. - [ ] Create `{entity}.repository.ts` interface. 2. **Application Layer**: - [ ] Create `{entity}.dto.ts`. - [ ] Create use case files (one per operation). - [ ] Create `index.ts` and export artifacts. 3. **Infrastructure Layer**: - [ ] Implement repository in `{entity}.repository.ts`. - [ ] Create controller in `{entity}.controller.ts`. - [ ] Add routes to `src/app.routes.ts`. 4. **Database**: - [ ] Create schema in `src/db/schemas/{entities}.ts`. - [ ] define relations. - [ ] Run migrations: `bun run db:push`. 5. **Testing**: - [ ] Create unit tests. - [ ] Create integration tests. - [ ] Create E2E tests (if needed).

authentication-identity

Scan your own AI components