eff7e339af
- Remove legacy rule files (documentation.mdc, general_development.mdc, etc.) - Implement new meta-rule system with core, app, and feature categories - Add meta-rule files for different workflows (bug diagnosis, feature planning, etc.) - Create organized directory structure: core/, app/, features/, database/, etc. - Add comprehensive README.md for rules documentation - Establish new rule architecture with always-on and workflow-specific rules This restructuring improves rule organization, enables better workflow management, and provides clearer separation of concerns for different development tasks.
187 lines
4.9 KiB
Plaintext
187 lines
4.9 KiB
Plaintext
|
|
# 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
|