# Build Architecture Guard Directive

**Author**: Matthew Raymer
**Date**: 2025-08-22
**Status**: 🎯 **ACTIVE** - Build system protection guidelines

## Purpose

Protect the TimeSafari building architecture from unauthorized changes that
could break the multi-platform build pipeline, deployment processes, or
development workflow. This directive ensures all build system modifications
follow proper review, testing, and documentation procedures.

**Note**: Recent Android build system enhancements (2025-08-22) include
  sophisticated asset validation, platform-specific API routing, and automatic
  resource regeneration. These features require enhanced testing and validation
  procedures.

## Protected Architecture Components

### Core Build Infrastructure

- **Vite Configuration Files**: `vite.config.*.mts` files

- **Build Scripts**: All scripts in `scripts/` directory

- **Package Scripts**: `package.json` build-related scripts

- **Platform Configs**: `capacitor.config.ts`, `electron/`, `android/`,

  `ios/`

- **Docker Configuration**: `Dockerfile`, `docker-compose.yml`

- **Environment Files**: `.env.*`, `.nvmrc`, `.node-version`

### Android-Specific Build Validation

- **Asset Validation Scripts**:

  `validate_android_assets()` function and resource checking

- **Resource Generation**: `capacitor-assets` integration and verification

- **Platform-Specific IP Handling**:

  Android emulator vs physical device API routing

- **Build Mode Validation**: Development/test/production mode handling

- **Resource Fallback Logic**:

  Automatic regeneration of missing Android resources

### Critical Build Dependencies

- **Build Tools**: Vite, Capacitor, Electron, Android SDK, Xcode

- **Asset Management**: `capacitor-assets.config.json`, asset scripts

- **Testing Infrastructure**: Playwright, Jest, mobile test scripts

- **CI/CD Pipeline**: GitHub Actions, build validation scripts

- **Service Worker Assembly**: `sw_scripts/`, `sw_combine.js`, WASM copy steps

## Change Authorization Requirements

### Level 1: Minor Changes (Requires Review)

- Documentation updates to `BUILDING.md`

- Non-breaking script improvements

- Test additions or improvements

- Asset configuration updates

**Process**: Code review + basic testing

### Level 2: Moderate Changes (Requires Testing)

- New build script additions

- Environment variable changes

- Dependency version updates

- Platform-specific optimizations

- **Build script argument parsing**:

  New flag handling (--api-ip, --auto-run, --deploy)

- **Platform-specific environment overrides**:

  Android API server IP customization

- **Asset regeneration logic**: Automatic fallback for missing Android resources

**Process**: Code review + platform testing + documentation update

### Level 3: Major Changes (Requires ADR)

- Build system architecture changes

- New platform support

- Breaking changes to build scripts

- Major dependency migrations

**Process**: ADR creation + comprehensive testing + team review

## Prohibited Actions

### ❌ Never Allow Without ADR

- **Delete or rename** core build scripts

- **Modify** `package.json` build script names

- **Change** Vite configuration structure

- **Remove** platform-specific build targets

- **Alter** Docker build process

- **Modify** CI/CD pipeline without testing

### ❌ Never Allow Without Testing

- **Update** build dependencies

- **Change** environment configurations

- **Modify** asset generation scripts

- **Alter** test infrastructure

- **Update** platform SDK versions

---

**See also**:

- `.cursor/rules/architecture/build_validation.mdc` for

  detailed validation procedures

- `.cursor/rules/architecture/build_testing.mdc` for testing requirements

**Status**: Active build protection guidelines
**Priority**: Critical
**Estimated Effort**: Ongoing reference
**Dependencies**: None
**Stakeholders**: Development team, DevOps team, Build team

**Estimated Effort**: Ongoing vigilance
**Dependencies**: All build system components
**Stakeholders**: Development team, DevOps, Platform owners
**Next Review**: 2025-09-22

## Model Implementation Checklist

### Before Build Changes

- [ ] **Change Level**: Determine if change is L1, L2, or L3
- [ ] **Impact Assessment**: Assess impact on build system architecture
- [ ] **ADR Requirement**: Check if ADR is required for major changes
- [ ] **Testing Planning**: Plan appropriate testing for change level

### During Build Changes

- [ ] **Guard Compliance**: Ensure changes comply with build architecture guard
- [ ] **Documentation**: Document changes according to level requirements
- [ ] **Testing**: Execute appropriate testing for change level
- [ ] **Review Process**: Follow required review process for change level

### After Build Changes

- [ ] **Validation**: Verify build system still functions correctly
- [ ] **Documentation Update**: Update relevant documentation
- [ ] **Team Communication**: Communicate changes to affected teams
- [ ] **Monitoring**: Monitor for any build system issues