You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
186 lines
4.9 KiB
186 lines
4.9 KiB
|
|
# 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
|
|
|