SerpentRace/Documentations/BUILD.md

# 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