kentbull/crowd-funder-for-time-pwa
1
0
Fork 0
forked from trent_larson/crowd-funder-for-time-pwa
Code Issues Pull Requests Projects Releases Wiki Activity

docs: comprehensive documentation updates and modernization

Browse Source 
- Update BUILDING.md with current build system information
- Modernize various README files across the project
- Update CHANGELOG.md with recent changes
- Improve documentation consistency and formatting
- Update platform-specific documentation (iOS, Electron, Docker)
- Enhance test documentation and build guides
This commit is contained in:
Matthew Raymer
2025-08-20 13:02:01 +00:00
parent 963ff9234f
commit 2d17bfd3b4
43 changed files with 1022 additions and 267 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
electron/README-BUILDING.md
View File

@@ -18,6 +18,7 @@ This guide covers building and running the TimeSafari Electron application for d
## Quick Start
### Development Mode
```bash
# Start development server
npm run build:electron:dev
@@ -28,6 +29,7 @@ npm run electron:start
```
### Production Builds
```bash
# Build for current platform
npm run build:electron:prod
@@ -48,16 +50,19 @@ npm run build:electron:deb # Linux DEB package
The Electron app enforces single instance operation to prevent database conflicts and resource contention:
### Implementation
- Uses Electron's built-in `app.requestSingleInstanceLock()`
- Second instances exit immediately with user-friendly message
- Existing instance focuses and shows informational dialog
### Behavior
- **First instance**: Starts normally and acquires lock
- **Second instance**: Detects existing instance, exits immediately
- **User experience**: Clear messaging about single instance requirement
### Benefits
- Prevents database corruption from concurrent access
- Avoids resource conflicts
- Maintains data integrity
@@ -66,6 +71,7 @@ The Electron app enforces single instance operation to prevent database conflict
## Build Configuration
### Environment Modes
```bash
# Development (default)
npm run build:electron:dev
@@ -78,6 +84,7 @@ npm run build:electron:prod
```
### Platform-Specific Builds
```bash
# Windows
npm run build:electron:windows:dev
@@ -96,6 +103,7 @@ npm run build:electron:linux:prod
```
### Package Types
```bash
# Linux AppImage
npm run build:electron:appimage:dev
@@ -116,26 +124,31 @@ npm run build:electron:deb:prod
## Platform-Specific Requirements
### Windows
- Windows 10+ (64-bit)
- Visual Studio Build Tools (for native modules)
### macOS
- macOS 10.15+ (Catalina)
- Xcode Command Line Tools
- Code signing certificate (for distribution)
### Linux
- Ubuntu 18.04+ / Debian 10+ / CentOS 7+
- Development headers for native modules
## Database Configuration
### SQLite Integration
- Uses native Node.js SQLite3 for Electron
- Database stored in user's app data directory
- Automatic migration from IndexedDB (if applicable)
### Single Instance Protection
- File-based locking prevents concurrent database access
- Automatic cleanup on app exit
- Graceful handling of lock conflicts
@@ -143,11 +156,13 @@ npm run build:electron:deb:prod
## Security Features
### Content Security Policy
- Strict CSP in production builds
- Development mode allows localhost connections
- Automatic configuration based on build mode
### Auto-Updater
- Disabled in development mode
- Production builds check for updates automatically
- AppImage builds skip update checks
@@ -157,6 +172,7 @@ npm run build:electron:deb:prod
### Common Issues
#### Build Failures
```bash
# Clean and rebuild
npm run clean:electron
@@ -164,6 +180,7 @@ npm run build:electron:dev
```
#### Native Module Issues
```bash
# Rebuild native modules
cd electron
@@ -171,16 +188,19 @@ npm run electron:rebuild
```
#### Single Instance Conflicts
- Ensure no other TimeSafari instances are running
- Check for orphaned processes: `ps aux | grep electron`
- Restart system if necessary
#### Database Issues
- Check app data directory permissions
- Verify SQLite database integrity
- Clear app data if corrupted
### Debug Mode
```bash
# Enable debug logging
DEBUG=* npm run build:electron:dev
@@ -203,6 +223,7 @@ electron/
## Development Workflow
1. **Start Development**
```bash
npm run build:electron:dev
```
@@ -212,11 +233,13 @@ electron/
- Changes auto-reload in development
3. **Test Build**
```bash
npm run build:electron:test
```
4. **Production Build**
```bash
npm run build:electron:prod
```
@@ -224,16 +247,19 @@ electron/
## Performance Considerations
### Memory Usage
- Monitor renderer process memory
- Implement proper cleanup in components
- Use efficient data structures
### Startup Time
- Lazy load non-critical modules
- Optimize database initialization
- Minimize synchronous operations
### Database Performance
- Use transactions for bulk operations
- Implement proper indexing
- Monitor query performance
@@ -251,16 +277,19 @@ electron/
## Deployment
### Distribution
- Windows: `.exe` installer
- macOS: `.dmg` disk image
- Linux: `.AppImage` or `.deb` package
### Code Signing
- Windows: Authenticode certificate
- macOS: Developer ID certificate
- Linux: GPG signing (optional)
### Auto-Updates
- Configured for production builds
- Disabled for development and AppImage
- Handles update failures gracefully
@@ -269,4 +298,4 @@ electron/
**Last Updated**: 2025-07-11
**Version**: 1.0.3-beta
**Status**: Production Ready
**Status**: Production Ready

34
electron/README.md
View File

@@ -56,21 +56,25 @@ npm run build:electron:dmg:prod
```
**Stage 1: Web Build**
- Vite builds web assets with Electron configuration
- Environment variables loaded based on build mode
- Assets optimized for desktop application
**Stage 2: Capacitor Sync**
- Copies web assets to Electron app directory
- Syncs Capacitor configuration and plugins
- Prepares native module bindings
**Stage 3: TypeScript Compile**
- Compiles Electron main process TypeScript
- Rebuilds native modules for target platform
- Generates production-ready JavaScript
**Stage 4: Package Creation**
- Creates platform-specific installers
- Generates distribution packages
- Signs applications (when configured)
@@ -82,6 +86,7 @@ npm run build:electron:dmg:prod
**Purpose**: Local development and testing
**Command**: `npm run build:electron:dev`
**Features**:
- Hot reload enabled
- Debug tools available
- Development logging
@@ -92,6 +97,7 @@ npm run build:electron:dmg:prod
**Purpose**: Staging and testing environments
**Command**: `npm run build:electron -- --mode test`
**Features**:
- Test API endpoints
- Staging configurations
- Optimized for testing
@@ -102,6 +108,7 @@ npm run build:electron:dmg:prod
**Purpose**: Production deployment
**Command**: `npm run build:electron -- --mode production`
**Features**:
- Production optimizations
- Code minification
- Security hardening
@@ -116,6 +123,7 @@ npm run build:electron:dmg:prod
**Command**: `npm run build:electron:windows:prod`
**Features**:
- NSIS installer with custom options
- Desktop and Start Menu shortcuts
- Elevation permissions for installation
@@ -128,6 +136,7 @@ npm run build:electron:dmg:prod
**Command**: `npm run build:electron:mac:prod`
**Features**:
- Universal binary (x64 + arm64)
- DMG installer with custom branding
- App Store compliance (when configured)
@@ -140,6 +149,7 @@ npm run build:electron:dmg:prod
**Command**: `npm run build:electron:linux:prod`
**Features**:
- AppImage for universal distribution
- DEB package for Debian-based systems
- RPM package for Red Hat-based systems
@@ -152,6 +162,7 @@ npm run build:electron:dmg:prod
**Format**: Self-contained Linux executable
**Command**: `npm run build:electron:appimage:prod`
**Features**:
- Single file distribution
- No installation required
- Portable across Linux distributions
@@ -162,6 +173,7 @@ npm run build:electron:dmg:prod
**Format**: Debian package installer
**Command**: `npm run build:electron:deb:prod`
**Features**:
- Native package management
- Dependency resolution
- System integration
@@ -172,6 +184,7 @@ npm run build:electron:dmg:prod
**Format**: macOS disk image
**Command**: `npm run build:electron:dmg:prod`
**Features**:
- Native macOS installer
- Custom branding and layout
- Drag-and-drop installation
@@ -293,6 +306,7 @@ Local Electron scripts for building:
### Environment Variables
**Development**:
```bash
VITE_API_URL=http://localhost:3000
VITE_DEBUG=true
@@ -301,6 +315,7 @@ VITE_ENABLE_DEV_TOOLS=true
```
**Testing**:
```bash
VITE_API_URL=https://test-api.timesafari.com
VITE_DEBUG=false
@@ -309,6 +324,7 @@ VITE_ENABLE_DEV_TOOLS=false
```
**Production**:
```bash
VITE_API_URL=https://api.timesafari.com
VITE_DEBUG=false
@@ -347,6 +363,7 @@ electron/
### Common Issues
**TypeScript Compilation Errors**:
```bash
# Clean and rebuild
npm run clean:electron
@@ -354,18 +371,21 @@ cd electron && npm run build
```
**Native Module Issues**:
```bash
# Rebuild native modules
cd electron && npm run build
```
**Asset Copy Issues**:
```bash
# Verify Capacitor sync
npx cap sync electron
```
**Package Creation Failures**:
```bash
# Check electron-builder configuration
# Verify platform-specific requirements
@@ -375,16 +395,19 @@ npx cap sync electron
### Platform-Specific Issues
**Windows**:
- Ensure Windows Build Tools installed
- Check NSIS installation
- Verify code signing certificates
**macOS**:
- Install Xcode Command Line Tools
- Configure code signing certificates
- Check app notarization requirements
**Linux**:
- Install required packages (rpm-tools, etc.)
- Check AppImage dependencies
- Verify desktop integration
@@ -394,11 +417,13 @@ npx cap sync electron
### Build Performance
**Parallel Builds**:
- Use concurrent TypeScript compilation
- Optimize asset copying
- Minimize file system operations
**Caching Strategies**:
- Cache node_modules between builds
- Cache compiled TypeScript
- Cache web assets when unchanged
@@ -406,11 +431,13 @@ npx cap sync electron
### Runtime Performance
**Application Startup**:
- Optimize main process initialization
- Minimize startup dependencies
- Use lazy loading for features
**Memory Management**:
- Monitor memory usage
- Implement proper cleanup
- Optimize asset loading
@@ -420,16 +447,19 @@ npx cap sync electron
### Code Signing
**Windows**:
- Authenticode code signing
- EV certificate for SmartScreen
- Timestamp server configuration
**macOS**:
- Developer ID code signing
- App notarization
- Hardened runtime
**Linux**:
- GPG signing for packages
- AppImage signing
- Package verification
@@ -437,12 +467,14 @@ npx cap sync electron
### Security Hardening
**Production Builds**:
- Disable developer tools
- Remove debug information
- Enable security policies
- Implement sandboxing
**Update Security**:
- Secure update channels
- Package integrity verification
- Rollback capabilities
@@ -496,4 +528,4 @@ npx cap sync electron
**Status**: Production ready
**Last Updated**: 2025-01-27
**Version**: 1.0
**Maintainer**: Matthew Raymer
**Maintainer**: Matthew Raymer