DEVELOPER GUIDE

Source code customization and building instructions

FOR SOURCE CODE BUYERS: You receive the complete source code archive but no pre-built applications. You must build the application yourself following this guide. This covers setup, customization, rebranding, and building from source.

QUICK START

IMPORTANT: You receive source code only - no pre-built executables. The dist/ folder is not included and must be generated through the build process.

Extract Source Code

Extract the provided archive to your development directory. You'll receive all source files but no built applications.

Check Build Environment (Optional)

npm run diagnose

This verifies your build environment and shows what will be configured automatically.

Install with Automatic Setup

npm install

This automatically configures your build environment and installs all dependencies.

Run in Development

npm run dev

Test that everything is working correctly.

Build for Production

npm run build-all

This creates the dist/ folder with platform-specific executables.

DEVELOPMENT ENVIRONMENT

System Requirements

Node.js: Version 18.0.0 or higher
npm: Version 8.0.0 or higher
Git: For version control
Python: Version 3.x (setuptools installed automatically)
Build Tools: Platform-specific compilers (configured automatically)

AUTOMATED SETUP: The build environment is now automatically configured when you run npm install. Python setuptools and other requirements are checked and installed automatically.

Automated Environment Configuration

The build environment is now automatically configured during installation. When you run npm install, the system will:

Check Node.js version and compatibility
Verify Python installation and setuptools
Detect and install missing dependencies
Configure platform-specific build tools
Provide specific instructions if manual setup is needed

Manual Setup (If Needed)

If automatic setup fails, you can manually install requirements:

# Check your environment
npm run diagnose

# Manual setup if needed
npm run setup

# Platform-specific commands:
# macOS: xcode-select --install
# Windows: Install Visual Studio Build Tools
# Linux: sudo apt-get install build-essential python3-setuptools

Verification

# Check overall build environment
npm run diagnose

# Verify specific components
node --version
python3 -c "import setuptools; print('setuptools OK')"

PROJECT STRUCTURE

crono-desktop/
├── main.js                   # Main Electron process
├── preload.js               # Preload script for renderer
├── package.json             # Dependencies and scripts
├── INSTALL.md               # Simple installation guide
├── BUILD-TROUBLESHOOTING.md # Quick reference for build issues
├── renderer/                # Frontend application
│   ├── index.html          # Main application UI
│   ├── style.css           # Application styling
│   └── app.js              # Frontend logic
├── db/                     # Database layer
│   └── database.js         # SQLite database class
├── documentation/          # Complete documentation
│   ├── index.html         # Documentation home
│   ├── content/           # Individual guide pages
│   └── assets/            # Shared CSS and resources
├── icons/                  # Application icons
├── scripts/                # Automated setup and utility scripts
│   ├── preinstall-setup.js # Automatic build environment setup
│   ├── diagnose-setup.js   # Environment diagnostic tool
│   ├── generate-icons.sh   # Icon generation
│   ├── package-dist.sh     # Distribution packaging
│   └── reset-database.js   # Database reset utility
└── dist/                   # Built applications (NOT INCLUDED - generated by build)
            

AUTOMATED SETUP: The project now includes automated setup scripts that configure your build environment. The dist/ folder is not included in your download and will be created when you run the build commands. All executables must be generated from source.

Key Scripts

preinstall-setup.js: Automatically runs before npm install to configure build environment
diagnose-setup.js: Comprehensive environment checker and diagnostic tool
INSTALL.md: Simple installation guide for new users
BUILD-TROUBLESHOOTING.md: Quick reference for common build issues

REBRANDING GUIDE

1. Application Name and Branding

Update package.json

{
  "name": "your-app-name",
  "productName": "Your App Name",
  "description": "Your app description",
  "author": "Your Company Name",
  "homepage": "https://your-website.com",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/your-repo.git"
  }
}
                    

Update Application Title

In renderer/index.html, update the title and header text:

<title>YOUR APP NAME - DATA ARCHIVE SYSTEM</title>
<h1><i class="fas fa-terminal"></i> YOUR APP</h1>
<p class="subtitle">DATA ARCHIVE SYSTEM v1.0</p>
                    

Update Window Title

In main.js, find the createWindow function:

mainWindow = new BrowserWindow({
  title: 'Your App Name - Data Archive System',
  // ... other options
});
                    

2. Visual Customization

Color Scheme (Optional)

To change the terminal color scheme, edit renderer/style.css:

/* Change primary color from green to your brand color */
:root {
  --primary-color: #00ff00;     /* Current green */
  --primary-color: #ff6b35;     /* Example: Orange */
  --primary-color: #6c5ce7;     /* Example: Purple */
}

/* Then replace all instances of #00ff00 with var(--primary-color) */
                    

Application Icons

Replace icons in the icons/ directory or use the icon generation script:

# 1. Replace icons/icon-source.svg with your design
# 2. Run the icon generator
npm run generate-icons
                    

Database Directory Name

In db/database.js, change the data directory name:

// Change from .crono to your app name
const dbDir = path.join(os.homedir(), '.your-app-name');
                    

3. Feature Customization

Default Categories: Modify insertDefaultCategories() in db/database.js
File Storage Structure: Customize file organization in copyFileToStructure()
UI Labels: Update all user-facing text in renderer/index.html
Export File Extensions: Change from .crono to your preferred extension

BUILD PROCESS

REQUIRED STEP: Since no pre-built applications are provided, you must build the application for your target platforms before distribution.

Available Build Scripts

# Development
npm start                 # Run in development mode
npm run dev              # Run with dev flag

# Building
npm run build-all        # Build for all platforms
npm run build-win        # Windows only
npm run build-mac        # macOS Intel only
npm run build-mac-arm    # macOS Apple Silicon only
npm run build-linux     # Linux only

# Distribution
npm run package          # Create distribution archives
npm run dist            # Build + package everything

# Maintenance
npm run clean           # Clean build directory
npm run rebuild-all     # Clean + build all
npm run reset-db        # Reset development database
            

Build Configuration

Build settings are configured in package.json under the "build" section:

"build": {
  "appId": "com.yourcompany.yourapp",
  "productName": "Your App Name",
  "directories": {
    "output": "dist"
  },
  "files": [
    "main.js",
    "preload.js",
    "renderer/**/*",
    "db/**/*",
    "node_modules/**/*",
    "package.json"
  ]
}
            

CUSTOMIZATION EXAMPLES

Adding New File Types

To add support for new file types, update the icon mapping in renderer/app.js:

getFileIconName(extension) {
  const ext = extension.toLowerCase().replace('.', '');
  const icons = {
    // Existing types
    pdf: 'file-pdf',
    doc: 'file-word',

    // Add your new types
    sketch: 'palette',
    figma: 'vector-square',
    psd: 'image'
  };
  return icons[ext] || 'file';
}
            

Custom Category Icons

Add new category icon options in renderer/index.html:

<select id="categoryIcon">
  <option value="folder">FOLDER</option>
  <option value="file-alt">DOCUMENT</option>

  <!-- Add your custom icons -->
  <option value="palette">DESIGN</option>
  <option value="code">CODE</option>
  <option value="camera">PHOTOGRAPHY</option>
</select>
            

Database Schema Modifications

To add new database fields, update the migration system in db/database.js:

migrateTo2() {
  try {
    // Add new column
    this.db.exec('ALTER TABLE files ADD COLUMN your_new_field TEXT');

    // Update schema version
    this.db.exec('PRAGMA user_version = 2');
  } catch (error) {
    console.error('Migration to version 2 failed:', error);
  }
}
            

DISTRIBUTION

Since you receive source code only, you must build and package everything for distribution. The automated build environment setup makes this process reliable across platforms:

RELIABLE BUILDS: With automated environment setup, builds are now consistent across different developer machines and platforms. No more build environment mismatches.

Streamlined Build Process

Verify Environment (Optional)

npm run diagnose

Check that your build environment is properly configured for all target platforms.

Build All Platforms

npm run build-all

Automatic environment setup ensures reliable cross-platform builds.

Package for Distribution

npm run package

This creates compressed archives in the archives/ directory

Generated Files

After building and packaging, you'll have distribution-ready archives:

dist/                        # Generated by build process
├── YourApp-win32-x64/      # Windows executable
├── YourApp-darwin-x64/     # macOS Intel executable
├── YourApp-darwin-arm64/   # macOS Apple Silicon executable
└── YourApp-linux-x64/      # Linux executable

archives/                    # Generated by package script
├── YourApp-windows-x64-v1.0.1.zip
├── YourApp-macos-intel-v1.0.1.zip
├── YourApp-macos-apple-silicon-v1.0.1.zip
└── YourApp-linux-x64-v1.0.1.tar.gz
                    

Distribution Best Practices

Environment Consistency: Use the same Node.js version across build machines
Automated Setup: Let the setup scripts configure build environments on CI/CD systems
Platform Testing: Test built executables on target platforms before release
Code Signing: Consider code signing for production releases

Code Signing (Optional)

For production releases, consider code signing:

Windows: Use SignTool with a valid certificate
macOS: Use Xcode with Apple Developer certificate
Linux: GPG signing for package integrity

SECURITY CONSIDERATIONS

Source Code Protection

Obfuscation: Consider JavaScript obfuscation for sensitive logic
Environment Variables: Remove any development keys or secrets
Database Encryption: The database uses SQLite without encryption by default
File Permissions: Ensure proper file access controls

User Data Privacy

All data is stored locally - no network requests are made
Export archives use password-based encryption
Database files are stored in user's home directory
No telemetry or analytics by default

DEBUGGING & BUILD ISSUES

Automated Build Diagnostics

Build issues are now automatically detected and resolved:

# Comprehensive environment check
npm run diagnose

# Automatic setup and repair
npm run setup

# Manual verification if needed
node --version
python3 -c "import setuptools; print('setuptools OK')"

Build Process

The standard build process now includes automatic environment setup:

Automatic Environment Check

When you run npm install, the preinstall script automatically checks and configures your build environment.

Dependency Installation

Native modules are compiled with the verified build environment.

Manual Intervention (Rare)

If automatic setup fails, specific instructions are provided for your platform.

Development Tools

# Environment setup and diagnostics
npm run setup      # Configure build environment
npm run diagnose   # Check environment status

# Development workflow
npm install        # Install with automatic setup
npm run dev        # Run in development mode
npm run build-all  # Build for all platforms

# Debugging and maintenance
npm run reset-db   # Reset development database
DEBUG=* npm run dev # Run with debug output

# Enable developer tools in main.js
mainWindow.webContents.openDevTools();
            

Standard Development Workflow

The simplified development process:

Environment check: npm run diagnose
Install dependencies: npm install (automatic setup included)
Start development: npm run dev
Build for distribution: npm run build-all

SIMPLIFIED SETUP: The build environment is now automatically configured. Manual setup is rarely needed thanks to the automated preinstall script.

LICENSING

IMPORTANT: Update the license information in package.json and add your own LICENSE file. Remove any references to the original project if required by your licensing terms.

Dependencies

Key dependencies and their licenses:

Electron: MIT License
better-sqlite3: MIT License
archiver: MIT License
yauzl: MIT License

LEARNING RESOURCES

Technologies Used

Electron: electronjs.org/docs
SQLite: sqlite.org/docs
Node.js: nodejs.org/docs
Better-SQLite3: API Documentation

Recommended Extensions

Adding auto-updater functionality
Implementing cloud backup integration
Adding file preview capabilities
Creating plugin architecture
Adding advanced search filters

DEVELOPMENT TIP: Start with small customizations and test thoroughly before making major changes. Keep the original source as a reference and maintain version control throughout your development process.

SUPPORT

Automated Troubleshooting

Build issues are now automatically diagnosed and resolved:

Environment check: Run npm run diagnose for comprehensive analysis
Automatic setup: Run npm run setup to configure environment
Clean install: npm install includes automatic environment setup
Manual verification: Only needed if automatic setup fails

When Reporting Issues

If automatic setup fails, include this information:

Operating system and version
Output of npm run diagnose
Output of npm run setup
Complete error message from npm install
Node.js version (node --version)

Getting Help

When developing with this source code:

Check the console for error messages and warnings
Use the browser developer tools for frontend debugging
Test builds on target platforms before distribution
Keep dependencies updated for security and compatibility
Remember: you must build everything from source - no pre-built files are provided
Environment setup is now automated - manual configuration rarely needed

First-Time Setup Checklist

✅ Extract source code archive
✅ Run environment check: npm run diagnose
✅ Install dependencies: npm install (automatic setup included)
✅ Test in development mode: npm run dev
✅ Customize/rebrand as needed
✅ Build for target platforms: npm run build-all
✅ Test built executables
✅ Package for distribution

Contributing Back

While this is commercial source code, consider:

Documenting any improvements you make
Sharing non-proprietary enhancements with the community
Following best practices for maintainable code
Keeping the codebase clean and well-commented

FINAL NOTE: This source code is provided as-is for customization and learning. No pre-built applications are included - you must build everything yourself. The build environment is now automatically configured during installation. Make sure to thoroughly test any modifications before deploying to end users. Always maintain backups of your working versions during development.