Code Patterns & Architecture

This document outlines the coding patterns, architectural decisions, and best practices used in the Comdeall backend application. These patterns ensure consistency, maintainability, and scalability across the codebase.

---

🏗️ Architecture Overview

Layered Architecture

┌──────────────────────────────────────────────────┐
│ API Layer │ ← Controllers, DTOs, Services
├──────────────────────────────────────────────────┤
│ Business Logic │ ← Domain Services, Validation
├──────────────────────────────────────────────────┤
│ Data Access Layer │ ← Repositories, DB Services
├──────────────────────────────────────────────────┤
│ Infrastructure │ ← Database, Redis, External APIs
└──────────────────────────────────────────────────┘

Module Structure

Each module in the Comdeall backend follows a consistent structure across the codebase. The modules are divided across two main directories: src/api for the API layer and src/db for the database layer.

src/
├── api/ # API Controllers & Services
│ ├── auth/ # Authentication & Authorization
│ ├── user/ # User Management (Parents, Therapists)
│ ├── assessment/ # Child Assessment Management
│ ├── lesson-plan/ # Lesson Plan Management
│ ├── appointments/ # Appointment Scheduling
│ ├── payment/ # Payment Processing
│ ├── subscription/ # Subscription Management
│ ├── notifications/ # Push Notifications
│ ├── support/ # Support Ticket System
│ └── media/ # File Upload/Management
├── db/ # Data Access Layer
│ ├── user/ # User Repository & DB Service
│ ├── assessment/ # Assessment Repository & DB Service
│ ├── lesson-plan/ # Lesson Plan Repository & DB Service
│ └── prisma/ # Database Schema
├── common/ # Shared Utilities
│ ├── dto/ # Common DTOs
│ ├── enum/ # Shared Enums
│ ├── helpers/ # Utility Functions
│ └── services/ # Common Services
├── background/ # Background Jobs & Queues
│ ├── queue/ # Queue Services & Processors
│ └── cron/ # Scheduled Jobs
├── interceptors/ # Request/Response Interceptors
├── middlewares/ # Custom Middlewares
└── socket/ # WebSocket Implementation

API Layer Structure

The API layer in src/api/module-name/ follows this structure:

module-name/
├── dto/
│   ├── create-*.dto.ts
│   ├── update-*.dto.ts
│   ├── *-response.dto.ts
│   └── [other DTOs]
├── enum/
│   ├── *-status.enum.ts
│   ├── *-type.enum.ts
│   └── [other enums]
├── helpers/
│   └── *-helper.ts
├── module-name.controller.ts
├── module-name.module.ts
├── module-name.service.ts
└── module-name.transform.ts

Database Layer Structure

The corresponding database layer in src/db/module-name/ follows this structure:

module-name/
├── module-name.repository.ts
└── module-name-db.service.ts

---

📝 Naming Conventions

Files & Classes

// Files: kebab-case
user.service.ts, create-parent.dto.ts

// Classes: PascalCase
export class UserService { }
export class CreateParentDto { }

// Enums: PascalCase with descriptive values
export enum UserRole {
  ADMIN = "ADMIN",
  PARENT = "PARENT", 
  THERAPIST = "THERAPIST"
}

---

🔧 Service Layer Patterns

API Service Structure

@Injectable()
export class UserService {
  private readonly logger = new Logger(UserService.name);
  
  constructor(
    private readonly userDBService: UserDBService,
    private readonly configService: ConfigService<EnvConfig>
  ) {}

  async createParent(parentData: CreateParentDto): Promise<InternalResponse> {
    // 1. Validate business rules
    // 2. Call DB service
    // 3. Queue background jobs
    // 4. Return standardized response
  }
}

Key Points:

• Services handle business logic
• Use dependency injection for DB services
• Always return InternalResponse format
• Log important operations

---

📋 DTO Patterns

Request DTOs with Validation

export class CreateParentDto {
  @ApiProperty({ description: 'Parent name', example: 'John Doe' })
  @IsString()
  @IsNotEmpty()
  @Length(3, 30)
  @Matches(REGEX.NAME)
  parent_name: string;

  @IsEmail()
  email: string;
}

Key Points:

• Use @ApiProperty for Swagger documentation
• Validate all inputs with class-validator decorators
• Use custom regex patterns for specific formats

Response Wrapper

export class CreateParentInput {
  @ValidateNested()
  @Type(() => CreateParentObject)
  input: CreateParentObject;
}

Key Points:

• Wrap complex DTOs in input objects
• Use @ValidateNested() for nested validation
• Use @Type() for proper transformation

---

🎮 Controller Patterns

Standard Controller

@Controller('user-management')
@ApiTags('User Management')
@UseGuards(JwtAuthGuard)
export class UserController {
  @Post('create-parent')
  @ApiOperation({ summary: 'Create parent account' })
  @ApiResponse({ status: 201, type: UserResponseDto })
  async createParent(@Body() dto: CreateParentDto): Promise<InternalResponse> {
    return this.userService.createParent(dto);
  }
}

Key Points:

• Use route names from RouteNames enum
• Add comprehensive Swagger documentation
• Apply appropriate guards (JWT, Roles)
• Keep controllers thin - delegate to services

---

🔄 Background Job Patterns

Queue Service

@Injectable()
export class EmailQueueService {
  async sendOtpEmail(data: IOtpEmailJob): Promise<void> {
    // Process email sending logic
    await this.emailService.sendEmail(emailData);
  }
}

Job Interface

export interface IOtpEmailJob {
  email: string;
  otp: string;
}

Key Points:

• Define clear interfaces for job data
• Use descriptive job names from JobName enum
• Handle errors gracefully in processors
• Log job processing for monitoring

---

🛡️ Error Handling

Service Level

async createUser(userData: CreateUserDto): Promise<InternalResponse> {
  try {
    // Business logic
    return { success: true, data: result };
  } catch (error) {
    this.logger.error(`Error: ${error.message}`, error.stack);
    throw new InternalServerErrorException('Operation failed');
  }
}

Key Points:

• Always wrap in try-catch
• Log errors with context
• Throw appropriate HTTP exceptions
• Return consistent response format

---

🔍 Validation Patterns

Custom Validators

@IsValidPhoneNumber({ message: 'Invalid phone format' })
contact: string;

Regex Constants

export const REGEX = {
  NAME: /^[a-zA-Z\s]+$/,
  PHONE: /^\+[1-9]\d{1,14}$/,
  EMAIL: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
};

Key Points:

• Create reusable regex patterns
• Use custom validators for complex validation
• Provide clear error messages

---

🔄 Interceptor Patterns

Response Transformation

@Injectable()
export class TransformInterceptor<T> implements NestInterceptor<T, ApiResponse<T>> {
  intercept(context: ExecutionContext, next: CallHandler): Observable<ApiResponse<T>> {
    return next.handle().pipe(
      map((data) => ({
        success: data?.success,
        message: data?.message,
        data: data?.data || data
      }))
    );
  }
}

Key Points:

• Standardize all API responses
• Exclude health/metrics endpoints
• Handle both HTTP and GraphQL contexts

---

🗄️ Database Patterns

Repository Pattern

@Injectable()
export class UserRepository {
  constructor(private readonly prisma: DBService) {}

  async getUserById(id: string) {
    return this.prisma.user.findUnique({
      where: { id },
      include: { parent: { include: { children: true } } }
    });
  }
}

DB Service Layer

@Injectable()
export class UserDBService {
  constructor(private readonly userRepository: UserRepository) {}
  
  async getUserById(id: string) {
    return this.userRepository.getUserById(id);
  }
}

Key Points:

• Repository handles raw database operations
• DB Service provides business-focused methods
• Use proper includes for related data
• Keep queries optimized with select/where clauses

---

🔐 Authentication Patterns

JWT Guard Usage

@UseGuards(JwtAuthGuard, RolesGuard)
@Roles(UserRole.ADMIN, UserRole.THERAPIST)
@Get('admin-only')
async adminEndpoint() { }

Key Points:

• Use JWT guard for authentication
• Use Roles guard for authorization
• Apply guards at controller or method level

---

📊 Logging & Monitoring

Structured Logging

private readonly logger = new Logger(ServiceName.name);

this.logger.log('Operation completed successfully');
this.logger.error('Operation failed', error.stack);
this.logger.debug('Debug information', context);

Key Points:

• Use NestJS Logger with service name
• Log at appropriate levels (log, error, debug, warn)
• Include context and stack traces for errors

---

🧪 Testing Patterns

Unit Test Structure

describe('UserService', () => {
  let service: UserService;
  let userDBService: UserDBService;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [
        UserService,
        { provide: UserDBService, useValue: mockUserDBService }
      ]
    }).compile();
    
    service = module.get<UserService>(UserService);
  });

  it('should create user successfully', async () => {
    // Arrange
    const userData = { name: 'John', email: 'john@test.com' };
    jest.spyOn(userDBService, 'createUser').mockResolvedValue(mockUser);

    // Act
    const result = await service.createUser(userData);

    // Assert
    expect(result.success).toBe(true);
    expect(userDBService.createUser).toHaveBeenCalledWith(userData);
  });
});

Key Points:

• Use AAA pattern (Arrange, Act, Assert)
• Mock dependencies properly
• Test both success and error scenarios
• Use descriptive test names

---

🚀 Performance Best Practices

Caching

@Cacheable('user', 300) // 5 minutes
async getUserById(id: string) {
  return this.userDBService.getUserById(id);
}

Database Optimization

// Use select to limit fields
async getUsersList() {
  return this.prisma.user.findMany({
    select: { id: true, email: true, role: true },
    take: 100
  });
}

Key Points:

• Cache frequently accessed data
• Use select to limit returned fields
• Implement pagination for large datasets
• Use proper database indexes

---

📋 Quick Reference

✅ Do's

• Use consistent naming conventions
• Implement proper error handling
• Validate all inputs
• Use dependency injection
• Follow repository pattern
• Log important operations
• Write comprehensive tests

❌ Don'ts

• Don't expose database models directly
• Don't use any type
• Don't ignore error handling
• Don't hardcode configuration
• Don't skip input validation
• Don't use console.log in production

---

This guide provides the essential patterns used in Comdeall backend. Follow these patterns for consistency and maintainability across the codebase.