# TimeSafari Electron Build Guide

**Author**: Matthew Raymer  
**Date**: 2025-07-11  
**Status**: **ACTIVE** - Production Ready

## Overview

This guide covers building and running the TimeSafari Electron application for desktop platforms (Windows, macOS, Linux).

## Prerequisites

- Node.js 18+ and npm
- TypeScript
- Electron Builder
- Platform-specific build tools (see below)

## Quick Start

### Development Mode

```bash
# Start development server
npm run build:electron:dev

# Or manually
cd electron
npm run electron:start
```

### Production Builds

```bash
# Build for current platform
npm run build:electron:prod

# Platform-specific builds
npm run build:electron:windows
npm run build:electron:mac
npm run build:electron:linux

# Package-specific builds
npm run build:electron:appimage  # Linux AppImage
npm run build:electron:dmg       # macOS DMG installer
npm run build:electron:deb       # Linux DEB package
```

## Single Instance Enforcement

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
- User-friendly error handling

## Build Configuration

### Environment Modes

```bash
# Development (default)
npm run build:electron:dev

# Testing
npm run build:electron:test

# Production
npm run build:electron:prod
```

### Platform-Specific Builds

```bash
# Windows
npm run build:electron:windows:dev
npm run build:electron:windows:test
npm run build:electron:windows:prod

# macOS
npm run build:electron:mac:dev
npm run build:electron:mac:test
npm run build:electron:mac:prod

# Linux
npm run build:electron:linux:dev
npm run build:electron:linux:test
npm run build:electron:linux:prod
```

### Package Types

```bash
# Linux AppImage
npm run build:electron:appimage:dev
npm run build:electron:appimage:test
npm run build:electron:appimage:prod

# macOS DMG
npm run build:electron:dmg:dev
npm run build:electron:dmg:test
npm run build:electron:dmg:prod

# Linux DEB
npm run build:electron:deb:dev
npm run build:electron:deb:test
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

## 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

## Troubleshooting

### Common Issues

#### Build Failures

```bash
# Clean and rebuild
npm run clean:electron
npm run build:electron:dev
```

#### Native Module Issues

```bash
# Rebuild native modules
cd electron
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
```

## File Structure

```
electron/
├── src/
│   ├── index.ts              # Main process entry point
│   ├── preload.ts            # Preload script
│   └── setup.ts              # App setup and configuration
├── assets/                   # App icons and resources
├── package.json              # Electron-specific dependencies
├── electron-builder.config.json  # Build configuration
└── tsconfig.json            # TypeScript configuration
```

## Development Workflow

1. **Start Development**

   ```bash
   npm run build:electron:dev
   ```

2. **Make Changes**
   - Edit source files in `src/`
   - Changes auto-reload in development

3. **Test Build**

   ```bash
   npm run build:electron:test
   ```

4. **Production Build**

   ```bash
   npm run build:electron:prod
   ```

## 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

## Security Checklist

- [ ] Content Security Policy configured
- [ ] Auto-updater properly configured
- [ ] Single instance enforcement active
- [ ] Database access properly secured
- [ ] IPC handlers validate input
- [ ] File system access restricted
- [ ] Network requests validated

## 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

---

**Last Updated**: 2025-07-11  
**Version**: 1.0.3-beta  
**Status**: Production Ready
