Wallet Module

What this module solves

Manages shared financial containers (wallets), balances, and wallet membership operations.

Endpoints

• POST /api/v1/wallet
• GET /api/v1/wallet
• PUT /api/v1/wallet/:walletId
• DELETE /api/v1/wallet/:walletId
• POST /api/v1/wallet/:walletId/members
• DELETE /api/v1/wallet/:walletId/members/:memberId

Validation rules

• Create/update wallet: name 3-20 chars, currency in supported ISO list, balance >= 0.
• Add member: valid email required.
• Schema file: backend/src/Shared/Schemas/walletSchema.ts.

Internal flow

Route	Controller	Use case	Repository	Route file trace
POST /wallet	WalletController.create	CreateWalletImpl	WalletRepositoryImpl	backend/src/Presentation/Routes/WalletRoutes.ts
GET /wallet	WalletController.listUserWallets	GetUserWalletsImpl	WalletRepositoryImpl	backend/src/Presentation/Routes/WalletRoutes.ts
PUT /wallet/:walletId	WalletController.edit	EditWalletImpl	WalletRepositoryImpl	backend/src/Presentation/Routes/WalletRoutes.ts
DELETE /wallet/:walletId	WalletController.delete	DeleteWalletImpl	WalletRepositoryImpl	backend/src/Presentation/Routes/WalletRoutes.ts
POST /wallet/:walletId/members	WalletController.addMember	AddWalletMemberImpl	WalletRepositoryImpl, UserRepositoryImpl	backend/src/Presentation/Routes/WalletRoutes.ts
DELETE /wallet/:walletId/members/:memberId	WalletController.deleteMember	DeleteWalletMemberImpl	WalletRepositoryImpl	backend/src/Presentation/Routes/WalletRoutes.ts

Controller: backend/src/Presentation/Controllers/WalletController.ts.

Common errors

• USER_NOT_AUTHENTICATED (401).
• WALLET_NOT_FOUND (404).
• WALLET_ALREADY_EXISTS (400).
• INSUFFICIENT_PERMISSIONS (403).

Testing notes

• E2E file: backend/src/tests/e2e/wallet/wallet-crud.e2e.test.ts.
• Unit examples:
  • backend/src/tests/unit/add-wallet-member-impl.test.ts

Quick snippets

1) cURL request example

curl -X POST "https://budgeti-backend.johandercampos.com/api/v1/wallet" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Wallet",
    "currency": "USD",
    "balance": 1500
  }'

2) Success JSON response example

{
  "code": "WALLET_CREATED",
  "message": "Wallet created successfully",
  "wallet": {
    "id": "wlt_123",
    "name": "Main Wallet",
    "currency": "USD",
    "balance": 1500,
    "ownerId": "usr_123"
  }
}

3) Common error JSON response example

{
  "code": "WALLET_NOT_FOUND",
  "message": "Wallet not found",
  "error": "Wallet not found"
}

4) Tiny internal trace snippet

// WalletController.create
const userId = req.user?.userId ?? req.userId;
const created = await createWalletUseCase.execute(req.body, userId);

return res.status(201).json({
  ...buildSuccessResponse(SuccessCodes.WALLET_CREATED),
  wallet: created,
});