Architecture

Backend Architecture

Overview#

Haddock’s backend is built on a modular, microservices-inspired architecture while maintaining the simplicity of a monolithic application. The core is built with NestJS, following clean architecture principles.

Core Components#

Module Structure#

src/
├── app.module.ts          # Root module
├── auth/                  # Authentication
├── project/              # Project management
├── vm/                   # VM operations
├── websockets/           # Real-time communication
└── shared/              # Shared utilities

Key Modules#

1. Auth Module

   • JWT authentication
   • GitHub OAuth integration
   • Role-based access control

2. Project Module

   • Project CRUD operations
   • GitHub repository integration
   • Team collaboration features

3. VM Module

   • VM provisioning
   • State management
   • Resource allocation

4. WebSocket Module

   • Real-time updates
   • Event broadcasting
   • Connection management

Data Flow#

1. Request Processing

   graph LR A[Client Request] --> B[Guard] B --> C[Controller] C --> D[Service] D --> E[Repository] E --> F[Database]

2. Event Processing

   graph LR A[Event] --> B[EventEmitter] B --> C[EventHandler] C --> D[WebSocket] D --> E[Client]

Design Patterns#

Repository Pattern#

• Abstraction over data storage
• Clean separation of concerns
• Easier testing and maintenance

Dependency Injection#

• NestJS built-in DI container
• Loose coupling
• Better testability

Observer Pattern#

• Event-driven architecture
• WebSocket notifications
• Async operations

Database Schema#

Core Tables#

1. Users

   • Authentication info
   • Profile data
   • Permissions

2. Projects

   • Project metadata
   • GitHub integration
   • Team assignments

3. VMs

   • Resource allocation
   • State management
   • Monitoring data

Security#

Authentication Flow#

1. User authentication via GitHub
2. JWT token generation
3. Token validation on protected routes

Authorization#

• Role-based access control (RBAC)
• Resource-level permissions
• Team-based access

Performance#

Caching Strategy#

• Redis for session data
• Query result caching
• WebSocket connection pooling

Database Optimization#

• Connection pooling
• Query optimization
• Indexing strategy

Error Handling#

Global Exception Filter#

• Standardized error responses
• Error logging
• Client-friendly messages

Validation#

• DTO validation
• Request validation
• Business rule validation