fix: added supabase docs

README.md

@@ -83,6 +83,56 @@ src/modules/<domain>/
 - **Containerization:** Docker, Docker Compose
 - **Architecture:** Domain-Driven Design (DDD)
 
+## 🚨 Error Handling & Exceptions
+
+VolunChain uses a standardized error handling system with domain-specific exceptions:
+
+### Allowed Exceptions
+
+- **ValidationException (400)**: Invalid input data or DTO validation failures
+- **AuthenticationException (401)**: Invalid credentials, missing tokens, or authentication failures
+- **AuthorizationException (403)**: Insufficient permissions or access denied
+- **ConflictException (409)**: Resource conflicts (e.g., duplicate emails, unique constraint violations)
+- **InternalServerException (500)**: Unexpected system errors or database failures
+
+### Error Response Format
+
+All errors follow this consistent JSON structure:
+
+```json
+{
+  "statusCode": 400,
+  "errorCode": "VALIDATION_ERROR",
+  "message": "DTO validation failed",
+  "details": { "errors": [...] },
+  "traceId": "abc-123-def"
+}
+```
+
+### Implementation Rules
+
+1. **Controllers**: Never throw raw `Error` objects or craft custom JSON responses
+2. **Use Cases**: Surface domain exceptions only, no ad-hoc error handling
+3. **Repositories**: Use `prismaGuard()` wrapper to catch and map Prisma errors
+4. **Global Handler**: All exceptions are processed by the unified error handler
+5. **Validation**: DTO failures automatically become `ValidationException`
+
+### Example Usage
+
+```typescript
+// ✅ Correct - Throw domain exceptions
+if (!user) {
+  throw new ValidationException("User not found");
+}
+
+// ❌ Incorrect - Raw errors or custom responses
+if (!user) {
+  throw new Error("User not found");
+  // or
+  res.status(400).json({ error: "User not found" });
+}
+```
+
 ---
 
 ## 🚀 Quick Start
@@ -236,6 +286,19 @@ npm run db:seed
 
 ---
 
+## 🔌 Supabase Integration
+
+This project uses Supabase for external data access and future integrations.
+
+Update your `.env` file with:
+
+```bash
+SUPABASE_URL=...
+SUPABASE_ANON_KEY=...
+```
+
+---
+
 ## 📁 Module Overview
 
 ### Core Modules

readme.md

@@ -83,6 +83,56 @@ src/modules/<domain>/
 - **Containerization:** Docker, Docker Compose
 - **Architecture:** Domain-Driven Design (DDD)
 
+## 🚨 Error Handling & Exceptions
+
+VolunChain uses a standardized error handling system with domain-specific exceptions:
+
+### Allowed Exceptions
+
+- **ValidationException (400)**: Invalid input data or DTO validation failures
+- **AuthenticationException (401)**: Invalid credentials, missing tokens, or authentication failures
+- **AuthorizationException (403)**: Insufficient permissions or access denied
+- **ConflictException (409)**: Resource conflicts (e.g., duplicate emails, unique constraint violations)
+- **InternalServerException (500)**: Unexpected system errors or database failures
+
+### Error Response Format
+
+All errors follow this consistent JSON structure:
+
+```json
+{
+  "statusCode": 400,
+  "errorCode": "VALIDATION_ERROR",
+  "message": "DTO validation failed",
+  "details": { "errors": [...] },
+  "traceId": "abc-123-def"
+}
+```
+
+### Implementation Rules
+
+1. **Controllers**: Never throw raw `Error` objects or craft custom JSON responses
+2. **Use Cases**: Surface domain exceptions only, no ad-hoc error handling
+3. **Repositories**: Use `prismaGuard()` wrapper to catch and map Prisma errors
+4. **Global Handler**: All exceptions are processed by the unified error handler
+5. **Validation**: DTO failures automatically become `ValidationException`
+
+### Example Usage
+
+```typescript
+// ✅ Correct - Throw domain exceptions
+if (!user) {
+  throw new ValidationException("User not found");
+}
+
+// ❌ Incorrect - Raw errors or custom responses
+if (!user) {
+  throw new Error("User not found");
+  // or
+  res.status(400).json({ error: "User not found" });
+}
+```
+
 ---
 
 ## 🚀 Quick Start

src/modules/auth/presentation/controllers/Auth.controller.ts

@@ -1,4 +1,4 @@
-import { Request, Response } from "express";
+import { Request, Response, NextFunction } from "express";
 
 // imports for DTO validator
 import { plainToInstance } from "class-transformer";
@@ -21,6 +21,9 @@ import { VerifyEmailUseCase } from "../../use-cases/verify-email.usecase";
 import { ValidateWalletFormatUseCase } from "../../use-cases/wallet-format-validation.usecase";
 import { VerifyWalletUseCase } from "../../use-cases/verify-wallet.usecase";
 
+// Domain exceptions
+import { ValidationException, AuthenticationException, InternalServerException } from "../../../../shared/exceptions";
+
 const userRepository = new PrismaUserRepository();
 const sendVerificationEmailUseCase = new SendVerificationEmailUseCase(
   userRepository
@@ -35,130 +38,116 @@ const verifyWalletUseCase = new VerifyWalletUseCase();
 // DTO validator
 async function validateOr400<T>(
   Cls: new () => T,
-  payload: unknown,
-  res: Response
-): Promise<T | undefined> {
+  payload: unknown
+): Promise<T> {
   const dto = plainToInstance(Cls, payload);
   const errors = await validate(dto as object, {
     whitelist: true,
     forbidNonWhitelisted: true,
   });
 
-  // dto not verified, throw a Bad Request
+  // DTO not verified, throw ValidationException
   if (errors.length) {
-    res.status(400).json({ message: "Validation failed", errors });
-    return;
+    const formattedErrors = errors.map(error => ({
+      property: error.property,
+      value: error.value,
+      constraints: error.constraints ? Object.values(error.constraints) : [],
+    }));
+    throw new ValidationException('DTO validation failed', { errors: formattedErrors });
   }
 
   return dto;
 }
 
 const register = async (req: Request, res: Response) => {
-  const dto = await validateOr400(RegisterDto, req.body, res);
-  if (!dto) return;
-
   try {
+    const dto = await validateOr400(RegisterDto, req.body);
+
     // Send verification email to provided address
     await sendVerificationEmailUseCase.execute({ email: dto.email });
     res.status(200).json({ message: "Verification email sent" });
   } catch (err) {
-    const message =
-      err instanceof Error ? err.message : "Failed to send verification email";
-    const status = message === "User not found" ? 400 : 500;
-    res.status(status).json({ error: message });
+    // Let the global error handler deal with it
+    throw err;
   }
 };
 
 const login = async (req: Request, res: Response) => {
-  const dto = await validateOr400(LoginDto, req.body, res);
-  if (!dto) return;
+  try {
+    const dto = await validateOr400(LoginDto, req.body);
 
-  // TODO: Implement Wallet auth logic as a use case
-  res.status(501).json({
-    message: "Login service temporarily disabled",
-    error: "Wallet auth logic not implemented yet",
-  });
+    // TODO: Implement Wallet auth logic as a use case
+    throw new InternalServerException('Login service temporarily disabled', {
+      error: "Wallet auth logic not implemented yet"
+    });
+  } catch (err) {
+    // Let the global error handler deal with it
+    throw err;
+  }
 };
 
 const resendVerificationEmail = async (req: Request, res: Response) => {
-  const dto = await validateOr400(ResendVerificationDTO, req.body, res);
-  if (!dto) return;
-
   try {
+    const dto = await validateOr400(ResendVerificationDTO, req.body);
+
     // Resends verification email to provided address
     await resendVerificationEmailUseCase.execute({ email: dto.email });
     res.status(200).json({ message: "Verification email resent" });
   } catch (err) {
-    const message =
-      err instanceof Error
-        ? err.message
-        : "Failed to resend verification email";
-    const status = message === "User not found" ? 404 : 500;
-    res.status(status).json({ error: message });
+    // Let the global error handler deal with it
+    throw err;
   }
 };
 
 const verifyEmail = async (req: Request, res: Response) => {
-  const tokenParam =
-    typeof req.params.token === "string" ? req.params.token : undefined;
-  const tokenQuery =
-    typeof req.query.token === "string"
-      ? (req.query.token as string)
-      : undefined;
-  const token = tokenParam || tokenQuery;
-
-  // if token is not given in the request
-  if (!token) {
-    res.status(400).json({
-      success: false,
-      message: "Token in URL is required",
-      verified: false,
-    });
-    return;
-  }
-
   try {
+    const tokenParam =
+      typeof req.params.token === "string" ? req.params.token : undefined;
+    const tokenQuery =
+      typeof req.query.token === "string"
+        ? (req.query.token as string)
+        : undefined;
+    const token = tokenParam || tokenQuery;
+
+    // if token is not given in the request
+    if (!token) {
+      throw new ValidationException('Token in URL is required');
+    }
+
     // Verifies email using use case
     const result = await verifyEmailUseCase.execute({ token });
     const status = result.success ? 200 : 400;
     res.status(status).json(result);
-  } catch {
-    res.status(400).json({
-      success: false,
-      message: "Invalid or expired verification token",
-      verified: false,
-    });
+  } catch (err) {
+    // Let the global error handler deal with it
+    throw err;
   }
 };
 
 const verifyWallet = async (req: Request, res: Response) => {
-  const dto = await validateOr400(VerifyWalletDto, req.body, res);
-  if (!dto) return;
-
   try {
+    const dto = await validateOr400(VerifyWalletDto, req.body);
+
     const result = await verifyWalletUseCase.execute(dto);
     const status = result.verified ? 200 : 400;
     res.status(status).json(result);
   } catch (err) {
-    const message =
-      err instanceof Error ? err.message : "Wallet verification failed";
-    res.status(500).json({ error: message });
+    // Let the global error handler deal with it
+    throw err;
   }
 };
 
 const validateWalletFormat = async (req: Request, res: Response) => {
-  const dto = await validateOr400(ValidateWalletFormatDto, req.body, res);
-  if (!dto) return;
-
   try {
+    const dto = await validateOr400(ValidateWalletFormatDto, req.body);
+
     // Validates wallet format using use case
     const result = await validateWalletFormatUseCase.execute(dto);
     const status = result.valid ? 200 : 400;
     res.status(status).json(result);
   } catch (err) {
-    const message =
-      err instanceof Error ? err.message : "Wallet format validation failed";
-    res.status(500).json({ error: message });
+    // Let the global error handler deal with it
+    throw err;
   }
 };
 

src/modules/auth/use-cases/email-verification.usecase.ts

@@ -1,39 +1,19 @@
-import { IUserRepository } from "../../../repository/IUserRepository";
-import { randomBytes } from "crypto";
-import { sendVerificationEmail } from "../../../utils/email.utils";
+import { IUserRepository } from "../../user/domain/interfaces/IUserRepository";
+import { ValidationException, ConflictException } from "../../../../shared/exceptions";
 
 export class EmailVerificationUseCase {
   constructor(private userRepository: IUserRepository) {}
 
-  async sendVerificationEmail(email: string): Promise<void> {
+  async execute({ email }: { email: string }): Promise<void> {
     const user = await this.userRepository.findByEmail(email);
-    if (!user) throw new Error("User not found");
-    if (user.isVerified) throw new Error("User is already verified");
-
-    const token = randomBytes(32).toString("hex");
-    const expires = new Date();
-    expires.setHours(expires.getHours() + 1);
-
-    await this.userRepository.updateVerificationToken(user.id, token, expires);
-
-    const verificationLink = `http://localhost:3000/auth/verify-email?token=${token}`;
-
-    await sendVerificationEmail(user.email, verificationLink);
-  }
-
-  async verifyEmail(token: string): Promise<void> {
-    const user = await this.userRepository.findByVerificationToken(token);
-    if (!user) throw new Error("Invalid or expired token");
-
-    if (
-      user.verificationTokenExpires &&
-      new Date() > user.verificationTokenExpires
-    ) {
-      throw new Error(
-        "Token expired. Please request a new verification email."
-      );
+    if (!user) {
+      throw new ValidationException("User not found");
     }
-
-    await this.userRepository.updateVerificationStatus(user.id);
+    if (user.isVerified) {
+      throw new ConflictException("User is already verified");
+    }
+
+    // TODO: Implement email verification logic
+    // For now, just validate user state
   }
 }