forked from trent_larson/crowd-funder-for-time-pwa
docs: reorganize documentation structure with 7-item folder limits
- Create logical sub-folder classification for all documentation - Organize 91 migration files into component-specific folders - Separate user guides, build system, migration, and development docs - Maintain maximum 7 items per folder for easy navigation - Add comprehensive README and reorganization summary - Ensure all changes tracked in git with proper versioning Structure: - user-guides/ (3 items): user-facing documentation - build-system/ (3 items): core, platforms, automation - migration/ (6 items): assessments, testing, templates - development/ (4 items): tools and standards - architecture/, testing/, examples/ (ready for future docs) Total: 24 folders created, all within 7-item limits
This commit is contained in:
Matthew Raymer
470
docs/build-system/core/build-systems-overview.md
Normal file
470
docs/build-system/core/build-systems-overview.md
Normal file
@@ -0,0 +1,470 @@
|
||||
# TimeSafari Build Systems Overview
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-07-11
|
||||
**Status**: ✅ **COMPLETE** - All build systems documented and integrated
|
||||
|
||||
## Overview
|
||||
|
||||
TimeSafari supports multiple platforms and build targets through a unified build system architecture. This document provides a comprehensive overview of all build systems, their purposes, and how they work together.
|
||||
|
||||
## Build System Architecture
|
||||
|
||||
### Platform Support Matrix
|
||||
|
||||
| Platform | Build Script | Development | Testing | Production | Package Types |
|
||||
|----------|--------------|-------------|---------|------------|---------------|
|
||||
| **Web** | `build-web.sh` | ✅ Dev Server | ✅ Test Build | ✅ Prod Build | Docker Images |
|
||||
| **Android** | `build-android.sh` | ✅ Debug APK | ✅ Test APK | ✅ Release APK/AAB | APK, AAB |
|
||||
| **iOS** | `build-ios.sh` | ✅ Debug App | ✅ Test App | ✅ Release App | IPA |
|
||||
| **Electron** | `build-electron.sh` | ✅ Dev App | ✅ Test App | ✅ Prod App | AppImage, DEB, DMG, EXE |
|
||||
|
||||
### Build Script Locations
|
||||
|
||||
```bash
|
||||
scripts/
|
||||
├── build-web.sh # Web/PWA builds
|
||||
├── build-android.sh # Android mobile builds
|
||||
├── build-ios.sh # iOS mobile builds (future)
|
||||
├── build-electron.sh # Desktop builds
|
||||
└── common.sh # Shared build utilities
|
||||
```
|
||||
|
||||
## Unified Build Pattern
|
||||
|
||||
All build scripts follow a consistent pattern:
|
||||
|
||||
### 1. **Environment Setup**
|
||||
```bash
|
||||
# Set platform-specific environment variables
|
||||
VITE_PLATFORM=<platform>
|
||||
PWA: automatically enabled for web platforms
|
||||
VITE_GIT_HASH=<git-commit-hash>
|
||||
```
|
||||
|
||||
### 2. **Argument Parsing**
|
||||
```bash
|
||||
# Consistent command-line interface
|
||||
./scripts/build-<platform>.sh [--dev|--test|--prod] [options]
|
||||
```
|
||||
|
||||
### 3. **Build Process**
|
||||
```bash
|
||||
# Standard build flow
|
||||
1. Validate environment
|
||||
2. Clean build artifacts
|
||||
3. Build web assets (Vite)
|
||||
4. Platform-specific build
|
||||
5. Generate assets
|
||||
6. Create packages (if requested)
|
||||
```
|
||||
|
||||
### 4. **Error Handling**
|
||||
```bash
|
||||
# Consistent exit codes
|
||||
1: Cleanup failed
|
||||
2: Web build failed
|
||||
3: Platform build failed
|
||||
4: Asset generation failed
|
||||
5: Package creation failed
|
||||
```
|
||||
|
||||
## Web Build System
|
||||
|
||||
### Purpose
|
||||
Builds the web application for browser and PWA deployment.
|
||||
|
||||
### Key Features
|
||||
- **Development Server**: Hot reload with Vite
|
||||
- **PWA Support**: Service workers and manifest generation
|
||||
- **Docker Integration**: Containerized deployment
|
||||
- **Environment Modes**: Development, test, production
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Development (starts dev server)
|
||||
npm run build:web:dev
|
||||
|
||||
# Production build
|
||||
npm run build:web:prod
|
||||
|
||||
# Docker deployment
|
||||
npm run build:web:docker:prod
|
||||
```
|
||||
|
||||
### Output
|
||||
- **Development**: Vite dev server at http://localhost:8080
|
||||
- **Production**: Static files in `dist/` directory
|
||||
- **Docker**: Containerized application image
|
||||
|
||||
**Documentation**: [Web Build Scripts Guide](build-web-script-integration.md)
|
||||
|
||||
## Android Build System
|
||||
|
||||
### Purpose
|
||||
Builds Android mobile applications using Capacitor and Gradle.
|
||||
|
||||
### Key Features
|
||||
- **Capacitor Integration**: Web-to-native bridge
|
||||
- **Gradle Builds**: APK and AAB generation
|
||||
- **Asset Generation**: Icons and splash screens
|
||||
- **Device Deployment**: Direct APK installation
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Development build
|
||||
npm run build:android:dev
|
||||
|
||||
# Production APK
|
||||
npm run build:android:prod
|
||||
|
||||
# Deploy to device
|
||||
npm run build:android:deploy
|
||||
```
|
||||
|
||||
### Output
|
||||
- **Debug APK**: `android/app/build/outputs/apk/debug/app-debug.apk`
|
||||
- **Release APK**: `android/app/build/outputs/apk/release/app-release.apk`
|
||||
- **AAB Bundle**: `android/app/build/outputs/bundle/release/app-release.aab`
|
||||
|
||||
### Device Deployment
|
||||
```bash
|
||||
# Automatic deployment to connected device
|
||||
npm run build:android:deploy
|
||||
|
||||
# Manual deployment
|
||||
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
|
||||
```
|
||||
|
||||
**Documentation**: [Android Build Scripts Guide](android-build-scripts.md)
|
||||
|
||||
## iOS Build System
|
||||
|
||||
### Purpose
|
||||
Builds iOS mobile applications using Capacitor and Xcode.
|
||||
|
||||
### Key Features
|
||||
- **Capacitor Integration**: Web-to-native bridge
|
||||
- **Xcode Integration**: Native iOS builds
|
||||
- **Asset Generation**: Icons and splash screens
|
||||
- **Simulator Support**: iOS simulator testing
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Development build
|
||||
npm run build:ios:dev
|
||||
|
||||
# Production build
|
||||
npm run build:ios:prod
|
||||
|
||||
# Open Xcode
|
||||
npm run build:ios:studio
|
||||
```
|
||||
|
||||
### Output
|
||||
- **Debug App**: `ios/App/build/Debug-iphonesimulator/App.app`
|
||||
- **Release App**: `ios/App/build/Release-iphoneos/App.app`
|
||||
- **IPA Package**: `ios/App/build/Release-iphoneos/App.ipa`
|
||||
|
||||
**Documentation**: [iOS Build Scripts Guide](ios-build-scripts.md) *(Future)*
|
||||
|
||||
## Electron Build System
|
||||
|
||||
### Purpose
|
||||
Builds desktop applications for Windows, macOS, and Linux.
|
||||
|
||||
### Key Features
|
||||
- **Cross-Platform**: Windows, macOS, Linux support
|
||||
- **Package Formats**: AppImage, DEB, DMG, EXE
|
||||
- **Development Mode**: Direct app execution
|
||||
- **Single Instance**: Prevents multiple app instances
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Development (runs app directly)
|
||||
npm run build:electron:dev
|
||||
|
||||
# Production AppImage
|
||||
npm run build:electron:appimage:prod
|
||||
|
||||
# Production DMG
|
||||
npm run build:electron:dmg:prod
|
||||
```
|
||||
|
||||
### Output
|
||||
- **Development**: App runs directly (no files created)
|
||||
- **Packages**: Executables in `electron/dist/` directory
|
||||
- **AppImage**: `TimeSafari-1.0.3-beta.AppImage`
|
||||
- **DEB**: `TimeSafari_1.0.3-beta_amd64.deb`
|
||||
- **DMG**: `TimeSafari-1.0.3-beta.dmg`
|
||||
- **EXE**: `TimeSafari Setup 1.0.3-beta.exe`
|
||||
|
||||
**Documentation**: [Electron Build Scripts Guide](electron-build-scripts.md)
|
||||
|
||||
## Environment Management
|
||||
|
||||
### Environment Variables
|
||||
|
||||
All build systems use consistent environment variable patterns:
|
||||
|
||||
```bash
|
||||
# Platform identification
|
||||
VITE_PLATFORM=web|capacitor|electron
|
||||
|
||||
# PWA configuration
|
||||
PWA: automatically enabled for web platforms
|
||||
|
||||
# Build information
|
||||
VITE_GIT_HASH=<git-commit-hash>
|
||||
DEBUG_MIGRATIONS=0|1
|
||||
```
|
||||
|
||||
### Environment Files
|
||||
|
||||
```bash
|
||||
.env.development # Development environment
|
||||
.env.test # Testing environment
|
||||
.env.production # Production environment
|
||||
```
|
||||
|
||||
### Mode-Specific Configuration
|
||||
|
||||
Each build mode loads appropriate environment configuration:
|
||||
|
||||
- **Development**: Local development settings
|
||||
- **Test**: Testing environment with test APIs
|
||||
- **Production**: Production environment with live APIs
|
||||
|
||||
## Package.json Integration
|
||||
|
||||
### Script Organization
|
||||
|
||||
All build scripts are integrated into `package.json` with consistent naming:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
// Web builds
|
||||
"build:web": "./scripts/build-web.sh",
|
||||
"build:web:dev": "./scripts/build-web.sh --dev",
|
||||
"build:web:test": "./scripts/build-web.sh --test",
|
||||
"build:web:prod": "./scripts/build-web.sh --prod",
|
||||
|
||||
// Android builds
|
||||
"build:android": "./scripts/build-android.sh",
|
||||
"build:android:dev": "./scripts/build-android.sh --dev",
|
||||
"build:android:test": "./scripts/build-android.sh --test",
|
||||
"build:android:prod": "./scripts/build-android.sh --prod",
|
||||
|
||||
// iOS builds
|
||||
"build:ios": "./scripts/build-ios.sh",
|
||||
"build:ios:dev": "./scripts/build-ios.sh --dev",
|
||||
"build:ios:test": "./scripts/build-ios.sh --test",
|
||||
"build:ios:prod": "./scripts/build-ios.sh --prod",
|
||||
|
||||
// Electron builds
|
||||
"build:electron:dev": "./scripts/build-electron.sh --dev",
|
||||
"build:electron:test": "./scripts/build-electron.sh --test",
|
||||
"build:electron:prod": "./scripts/build-electron.sh --prod"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Legacy Compatibility
|
||||
|
||||
Legacy scripts are maintained as aliases for backward compatibility:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
// Legacy Android scripts (aliases)
|
||||
"build:capacitor:android": "npm run build:android",
|
||||
"build:capacitor:android:dev": "npm run build:android:dev",
|
||||
"build:capacitor:android:test": "npm run build:android:test",
|
||||
"build:capacitor:android:prod": "npm run build:android:prod"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Build Artifacts
|
||||
|
||||
### Common Artifacts
|
||||
|
||||
All build systems generate consistent artifacts:
|
||||
|
||||
```bash
|
||||
dist/ # Web build output
|
||||
├── index.html # Main HTML file
|
||||
├── assets/ # Compiled assets
|
||||
├── manifest.webmanifest # PWA manifest
|
||||
└── sw.js # Service worker
|
||||
|
||||
android/app/build/ # Android build output
|
||||
├── outputs/apk/debug/ # Debug APKs
|
||||
├── outputs/apk/release/ # Release APKs
|
||||
└── outputs/bundle/release/ # AAB bundles
|
||||
|
||||
ios/App/build/ # iOS build output
|
||||
├── Debug-iphonesimulator/ # Debug builds
|
||||
└── Release-iphoneos/ # Release builds
|
||||
|
||||
electron/dist/ # Electron packages
|
||||
├── *.AppImage # Linux AppImages
|
||||
├── *.deb # Linux DEB packages
|
||||
├── *.dmg # macOS DMG packages
|
||||
└── *.exe # Windows installers
|
||||
```
|
||||
|
||||
### Asset Generation
|
||||
|
||||
All platforms generate platform-specific assets:
|
||||
|
||||
```bash
|
||||
# Icons and splash screens
|
||||
npx capacitor-assets generate --android
|
||||
npx capacitor-assets generate --ios
|
||||
|
||||
# PWA assets
|
||||
npx vite build --config vite.config.web.mts
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Daily Development
|
||||
|
||||
```bash
|
||||
# Web development
|
||||
npm run build:web:dev # Starts dev server
|
||||
|
||||
# Android development
|
||||
npm run build:android:dev # Builds debug APK
|
||||
npm run build:android:deploy # Deploy to device
|
||||
|
||||
# Electron development
|
||||
npm run build:electron:dev # Runs app directly
|
||||
```
|
||||
|
||||
### Testing Workflow
|
||||
|
||||
```bash
|
||||
# Test all platforms
|
||||
npm run build:web:test
|
||||
npm run build:android:test
|
||||
npm run build:ios:test
|
||||
npm run build:electron:test
|
||||
```
|
||||
|
||||
### Production Workflow
|
||||
|
||||
```bash
|
||||
# Build all platforms for production
|
||||
npm run build:web:prod
|
||||
npm run build:android:prod
|
||||
npm run build:ios:prod
|
||||
npm run build:electron:prod
|
||||
|
||||
# Create distribution packages
|
||||
npm run build:electron:appimage:prod
|
||||
npm run build:electron:dmg:prod
|
||||
npm run build:electron:deb:prod
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Build Failures
|
||||
```bash
|
||||
# Clean all build artifacts
|
||||
npm run clean:all
|
||||
|
||||
# Rebuild from scratch
|
||||
npm run build:<platform>:dev
|
||||
```
|
||||
|
||||
#### Device Connection Issues
|
||||
```bash
|
||||
# Check Android device connection
|
||||
adb devices
|
||||
|
||||
# Check iOS device connection
|
||||
xcrun devicectl list devices
|
||||
```
|
||||
|
||||
#### Environment Issues
|
||||
```bash
|
||||
# Verify environment variables
|
||||
echo $VITE_PLATFORM
|
||||
echo "PWA: automatically enabled for web platforms"
|
||||
|
||||
# Check environment files
|
||||
ls -la .env*
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable verbose logging for all build scripts:
|
||||
|
||||
```bash
|
||||
# Verbose mode
|
||||
./scripts/build-<platform>.sh --verbose
|
||||
|
||||
# Debug environment
|
||||
DEBUG_MIGRATIONS=1 npm run build:<platform>:dev
|
||||
```
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
### Build Times (Typical)
|
||||
|
||||
| Platform | Development | Production | Package |
|
||||
|----------|-------------|------------|---------|
|
||||
| **Web** | 350ms | 8s | 12s |
|
||||
| **Android** | 45s | 60s | 75s |
|
||||
| **iOS** | 60s | 90s | 120s |
|
||||
| **Electron** | 15s | 25s | 45s |
|
||||
|
||||
### Optimization Features
|
||||
|
||||
- **Incremental Builds**: Only rebuild changed files
|
||||
- **Parallel Processing**: Multi-core build optimization
|
||||
- **Caching**: Build artifact caching
|
||||
- **Asset Optimization**: Image and code minification
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Build Security
|
||||
|
||||
- **Environment Isolation**: Separate dev/test/prod environments
|
||||
- **Secret Management**: Secure handling of API keys
|
||||
- **Code Signing**: Digital signatures for packages
|
||||
- **Dependency Scanning**: Regular security audits
|
||||
|
||||
### Distribution Security
|
||||
|
||||
- **Package Verification**: Checksum validation
|
||||
- **Code Signing**: Digital certificates for packages
|
||||
- **Update Security**: Secure update mechanisms
|
||||
- **Sandboxing**: Platform-specific security isolation
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Improvements
|
||||
|
||||
- **CI/CD Integration**: Automated build pipelines
|
||||
- **Cross-Platform Testing**: Unified test framework
|
||||
- **Performance Monitoring**: Build performance tracking
|
||||
- **Asset Optimization**: Advanced image and code optimization
|
||||
|
||||
### Platform Expansion
|
||||
|
||||
- **Windows Store**: Microsoft Store packages
|
||||
- **Mac App Store**: App Store distribution
|
||||
- **Google Play**: Play Store optimization
|
||||
- **App Store**: iOS App Store distribution
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-07-11
|
||||
**Version**: 1.0.3-beta
|
||||
**Status**: Production Ready
|
||||
Reference in New Issue
Block a user