Architecture Overview

Overview

The Haddock backend is built using NestJS, following a modular architecture with clear separation of concerns.

Core Architecture Principles

Module Structure

Each major feature is encapsulated in its own module, containing:

• Controllers - Handle HTTP requests
• Services - Implement business logic
• Repositories - Handle data access
• DTOs - Define data transfer objects
• Types/Interfaces - Define type contracts

Database Layer

• Uses Prisma as ORM
• PostgreSQL for persistent storage
• Redis for caching and job queues

Authentication & Authorization

• JWT-based authentication
• Role-based access control
• Multiple auth strategies (Local, GitHub OAuth)
• Secure password handling with bcrypt

Queue Processing

• Uses Bull for background job processing
• Handles long-running tasks like:
  • VM provisioning
  • Repository cloning
  • Domain verification
  • SSL certificate management

Key Components

Domain Management

domains/
├── dns/              # DNS verification and management
├── dto/              # Data transfer objects
└── services/         # Domain business logic

Virtual Machine Management

vm/
├── providers/        # Different VM providers
├── templates/        # VM configuration templates
└── services/         # VM lifecycle management

Project Management

project/
├── dto/              # Project DTOs
├── validator/        # Input validation
└── services/        # Project business logic

Data Flow

1. Request Handling

   • HTTP request hits controller
   • Authentication/authorization check
   • Input validation

2. Business Logic

   • Service layer processes request
   • Calls necessary repositories
   • Triggers background jobs if needed

3. Response

   • Data transformation via DTOs
   • Response serialization
   • WebSocket notifications if needed

Error Handling

• Global exception filter for consistent error responses
• Custom domain-specific exceptions
• Proper HTTP status code mapping
• Structured error responses

Testing Strategy

• Unit tests for services and repositories
• Integration tests for API endpoints
• E2E tests for critical workflows
• Mocked external dependencies