Categories Module

What this module solves

Allows users to organize transactions with personal categories and keep analytics meaningful.

Endpoints

• Canonical base: /api/v1/categories
  • POST /api/v1/categories
  • GET /api/v1/categories
  • PATCH /api/v1/categories/:categoryId
  • DELETE /api/v1/categories/:categoryId
• Compatibility alias base: /api/v1/category (same handlers and behavior).

Validation rules

• name is required, min 2 chars, max 10 chars.
• Schema file: backend/src/Shared/Schemas/categorySchema.ts.

Internal flow

Route	Controller	Use case	Repository	Route file trace
POST /categories	CategoryController.create	CreateCategoryImpl	CategoryRepositoryImpl	backend/src/Presentation/Routes/CategoryRoutes.ts
GET /categories	CategoryController.get	GetUserCategoriesImpl	CategoryRepositoryImpl	backend/src/Presentation/Routes/CategoryRoutes.ts
PATCH /categories/:categoryId	CategoryController.update	UpdateCategoryImpl	CategoryRepositoryImpl	backend/src/Presentation/Routes/CategoryRoutes.ts
DELETE /categories/:categoryId	CategoryController.delete	DeleteCategoryImpl	CategoryRepositoryImpl	backend/src/Presentation/Routes/CategoryRoutes.ts

Alias wiring (/category) lives in backend/src/Presentation/Routes/Index.ts.

Common errors

• CATEGORY_NAME_REQUIRED (400).
• CATEGORY_ALREADY_EXISTS or CATEGORY_NAME_ALREADY_EXIST (409).
• CATEGORY_ID_REQUIRED (400).
• USER_NOT_AUTHENTICATED (401).

Testing notes

• E2E file: backend/src/tests/e2e/category/category-crud.e2e.test.ts.
• Unit example: backend/src/tests/unit/update-category-impl.test.ts.

Quick snippets

1) cURL request example

curl -X POST "https://budgeti-backend.johandercampos.com/api/v1/categories" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Food",
    "walletId": "wlt_123"
  }'

2) Success JSON response example

{
  "code": "CATEGORY_CREATED",
  "message": "Category created successfully",
  "data": {
    "id": "cat_123",
    "name": "Food",
    "userId": "usr_123",
    "walletId": "wlt_123"
  }
}

3) Common error JSON response example

{
  "code": "CATEGORY_NAME_REQUIRED",
  "message": "Category name is required",
  "error": "Category name is required"
}

4) Tiny internal trace snippet

// CategoryController.create
const name = (req.body.name ?? '').toString().trim();
const userId = req.userId;

const category = await createCategoryImpl.execute(
  { name, walletId: req.body.walletId },
  userId,
);

return res.status(201).json({
  ...buildSuccessResponse(SuccessCodes.CATEGORY_CREATED),
  data: category,
});