Backend Complete: Interface Refactoring & Service Container Enhancements
Repository Interface Optimization: - Created IBaseRepository.ts and IPaginatedRepository.ts - Refactored all 7 repository interfaces to extend base interfaces - Eliminated ~200 lines of redundant code (70% reduction) - Improved type safety and maintainability Dependency Injection Improvements: - Added EmailService and GameTokenService to DIContainer - Updated CreateUserCommandHandler constructor for DI - Updated RequestPasswordResetCommandHandler constructor for DI - Enhanced testability and service consistency Environment Configuration: - Created comprehensive .env.example with 40+ variables - Organized into 12 logical sections (Database, Security, Email, etc.) - Added security guidelines and best practices - Documented all backend environment requirements Documentation: - Added comprehensive codebase review - Created refactoring summary report - Added frontend implementation guide Impact: Improved code quality, reduced maintenance overhead, enhanced developer experience
This commit is contained in:
@@ -0,0 +1,297 @@
|
||||
# SerpentRace Backend Build System
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the comprehensive build system for the SerpentRace backend application. The build system handles TypeScript compilation, database migrations, asset management, testing, and deployment.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Development build
|
||||
npm run build
|
||||
|
||||
# Production build with full validation
|
||||
npm run build:production
|
||||
|
||||
# Advanced build with migrations and tests
|
||||
npm run build:advanced:prod
|
||||
|
||||
# Development server with hot reload
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Build Scripts
|
||||
|
||||
### Basic Build Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `npm run build` | Standard build: clean → compile → copy assets |
|
||||
| `npm run build:clean` | Clean the dist directory |
|
||||
| `npm run build:compile` | Compile TypeScript to JavaScript |
|
||||
| `npm run build:copy-assets` | Copy non-TS files to dist directory |
|
||||
| `npm run build:docker` | Build for Docker (no tests/migrations) |
|
||||
|
||||
### Production Build Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `npm run build:production` | Full production build with linting, tests, and migrations |
|
||||
| `npm run build:advanced` | Advanced build script with custom options |
|
||||
| `npm run build:advanced:prod` | Advanced production build with all validations |
|
||||
| `npm run build:advanced:ci` | CI/CD friendly build (skips linting) |
|
||||
|
||||
### Development Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `npm run dev` | Start development server with hot reload |
|
||||
| `npm run watch` | Watch mode TypeScript compilation |
|
||||
| `npm run typecheck` | Type checking without code generation |
|
||||
|
||||
### Database Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `npm run migration:run` | Run pending database migrations |
|
||||
| `npm run migration:show` | Show migration status |
|
||||
| `npm run migration:generate <name>` | Generate new migration |
|
||||
| `npm run migration:create <name>` | Create empty migration |
|
||||
| `npm run migration:revert` | Revert last migration |
|
||||
| `npm run migration:full <name>` | Create, generate, and run migration |
|
||||
|
||||
### Testing Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `npm test` | Run all tests |
|
||||
| `npm run test:watch` | Run tests in watch mode |
|
||||
| `npm run test:coverage` | Run tests with coverage report |
|
||||
| `npm run test:redis` | Run Redis-specific tests |
|
||||
|
||||
### Deployment Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `npm run deploy:prod` | Build for production deployment |
|
||||
| `scripts/deploy.sh` | Full Linux/Mac deployment script |
|
||||
| `scripts/deploy.bat` | Full Windows deployment script |
|
||||
|
||||
## Advanced Build Script
|
||||
|
||||
The advanced build script (`scripts/build.ts`) supports various options:
|
||||
|
||||
```bash
|
||||
# Basic advanced build
|
||||
npm run build:advanced
|
||||
|
||||
# Production build with migrations and tests
|
||||
npm run build:advanced:prod
|
||||
|
||||
# CI/CD build (skips linting, includes tests and migrations)
|
||||
npm run build:advanced:ci
|
||||
```
|
||||
|
||||
### Build Options
|
||||
|
||||
- `--migrations`: Run database migrations during build
|
||||
- `--test`: Run tests during build
|
||||
- `--skip-lint`: Skip linting step
|
||||
- `--production`: Enable production mode (strict validation)
|
||||
|
||||
## Deployment Scripts
|
||||
|
||||
### Linux/Mac Deployment
|
||||
|
||||
```bash
|
||||
./scripts/deploy.sh [deploy|build-only|test-connections]
|
||||
```
|
||||
|
||||
Options:
|
||||
- `deploy` (default): Full deployment with validation
|
||||
- `build-only`: Build without connection testing
|
||||
- `test-connections`: Test database and Redis connections only
|
||||
|
||||
### Windows Deployment
|
||||
|
||||
```cmd
|
||||
scripts\deploy.bat [deploy|build-only|test-connections]
|
||||
```
|
||||
|
||||
Same options as Linux/Mac version.
|
||||
|
||||
### Required Environment Variables
|
||||
|
||||
The deployment scripts require these environment variables:
|
||||
|
||||
```bash
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
DB_USERNAME=postgres
|
||||
DB_PASSWORD=your_password
|
||||
DB_NAME=serpentrace
|
||||
JWT_SECRET=your_jwt_secret
|
||||
REDIS_HOST=localhost
|
||||
REDIS_PORT=6379
|
||||
```
|
||||
|
||||
## Build Process Flow
|
||||
|
||||
### Standard Build (`npm run build`)
|
||||
|
||||
1. **Clean** - Remove previous build artifacts
|
||||
2. **Lint** - Code quality checks (if configured)
|
||||
3. **Compile** - TypeScript compilation
|
||||
4. **Copy Assets** - Copy non-TS files to dist
|
||||
5. **Post-build** - Validation and cleanup
|
||||
|
||||
### Production Build (`npm run build:production`)
|
||||
|
||||
1. **Clean** - Remove previous build artifacts
|
||||
2. **Lint** - Code quality checks
|
||||
3. **Test** - Run test suite
|
||||
4. **Migrations** - Apply database migrations
|
||||
5. **Compile** - TypeScript compilation
|
||||
6. **Copy Assets** - Copy non-TS files to dist
|
||||
7. **Validate** - Ensure build integrity
|
||||
|
||||
### Advanced Build (`npm run build:advanced`)
|
||||
|
||||
Provides fine-grained control over the build process with comprehensive logging and error handling.
|
||||
|
||||
## Asset Management
|
||||
|
||||
The build system automatically copies these file types to the dist directory:
|
||||
|
||||
- `.json` files (configuration, data)
|
||||
- `.html` files (templates)
|
||||
- `.css` files (stylesheets)
|
||||
- Image files (`.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.ico`)
|
||||
- Font files (`.woff`, `.woff2`, `.ttf`, `.eot`)
|
||||
|
||||
Excluded directories:
|
||||
- `node_modules`
|
||||
- `.git`
|
||||
- `tests`
|
||||
- `__tests__`
|
||||
|
||||
## TypeScript Configuration
|
||||
|
||||
The build system uses the following TypeScript settings:
|
||||
|
||||
- **Target**: ES2020
|
||||
- **Module**: CommonJS
|
||||
- **Output Directory**: `./dist`
|
||||
- **Source Maps**: Enabled
|
||||
- **Declarations**: Enabled for type definitions
|
||||
- **Strict Mode**: Enabled for type safety
|
||||
|
||||
## Migration Management
|
||||
|
||||
### Creating Migrations
|
||||
|
||||
```bash
|
||||
# Create empty migration
|
||||
npm run migration:create AddNewTable
|
||||
|
||||
# Generate migration from entity changes
|
||||
npm run migration:generate AddNewTable
|
||||
|
||||
# Full migration workflow (create + generate + run)
|
||||
npm run migration:full AddNewTable
|
||||
```
|
||||
|
||||
### Migration Best Practices
|
||||
|
||||
1. Always backup database before running migrations in production
|
||||
2. Test migrations in development environment first
|
||||
3. Use descriptive migration names
|
||||
4. Review generated migrations before running them
|
||||
|
||||
## Docker Integration
|
||||
|
||||
The build system is optimized for Docker deployments:
|
||||
|
||||
```dockerfile
|
||||
# Use build:docker for container builds
|
||||
RUN npm run build:docker
|
||||
|
||||
# Or use production build for full validation
|
||||
RUN npm run build:production
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Build fails with "Cannot find module"**
|
||||
- Run `npm ci` to ensure all dependencies are installed
|
||||
- Check TypeScript paths configuration
|
||||
|
||||
2. **Migration errors during build**
|
||||
- Verify database connection parameters
|
||||
- Ensure database exists and is accessible
|
||||
- Check migration files for syntax errors
|
||||
|
||||
3. **Asset copying fails**
|
||||
- Verify file permissions
|
||||
- Check disk space availability
|
||||
- Ensure source files exist
|
||||
|
||||
4. **TypeScript compilation errors**
|
||||
- Run `npm run typecheck` for detailed error messages
|
||||
- Check tsconfig.json configuration
|
||||
- Verify all type definitions are installed
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable verbose logging by setting the environment variable:
|
||||
|
||||
```bash
|
||||
export DEBUG=serpentrace:*
|
||||
npm run build:advanced
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Build Performance Tips
|
||||
|
||||
1. Use `npm ci` instead of `npm install` in CI/CD
|
||||
2. Enable TypeScript incremental compilation for development
|
||||
3. Use `--skip-lint` in CI if linting is handled separately
|
||||
4. Cache node_modules in CI/CD pipelines
|
||||
|
||||
### Runtime Performance
|
||||
|
||||
The build system optimizes the output for production:
|
||||
|
||||
- Source maps for debugging (can be disabled in production)
|
||||
- Type declarations for library usage
|
||||
- Compressed and optimized JavaScript output
|
||||
|
||||
## Monitoring and Logging
|
||||
|
||||
Build logs include:
|
||||
- Timestamps for each build step
|
||||
- Error details with stack traces
|
||||
- Performance metrics (build duration)
|
||||
- Validation results
|
||||
|
||||
Production builds create detailed logs in the `logs/` directory.
|
||||
|
||||
## Contributing
|
||||
|
||||
When modifying the build system:
|
||||
|
||||
1. Test changes with both development and production builds
|
||||
2. Update this documentation for any new scripts or options
|
||||
3. Ensure backward compatibility
|
||||
4. Add appropriate error handling and logging
|
||||
|
||||
## Support
|
||||
|
||||
For build system issues:
|
||||
1. Check this documentation
|
||||
2. Review error logs in the console
|
||||
3. Verify environment variables are set correctly
|
||||
4. Test with a clean `node_modules` installation
|
||||
Reference in New Issue
Block a user