# Nailed It Construction - Gallery Management

## Overview

This document explains how to manage the image gallery for Nailed It Construction. The gallery system uses **auto-discovery** - meaning you simply add images to a folder, and the system handles the rest.

## Quick Start

### 1. Add Your Images

Place your construction project photos in the following directory:

```
public_html/assets/gallery/
```

**Supported formats:** `.jpg`, `.jpeg`, `.png`, `.webp`, `.svg`, `.gif` (case-insensitive)

### 2. Run the Scan Script

After adding images, run the scan script to generate the gallery data:

```bash
# Navigate to your public_html directory
cd /home/HexNemesis/web/naileditconstruct.com/public_html/

# Run the scan script
node scan-gallery.js
```

### 3. That's It!

The script will:
- Scan the `assets/gallery/` directory
- Categorize images based on filename prefixes
- Generate a `gallery-data.json` file
- Your gallery page will automatically display the new images

## Image Organization

### Automatic Categorization

Images are automatically categorized based on their filename prefixes:

| Filename Prefix | Category |
|----------------|----------|
| `deck_` | Custom Decks |
| `cabinet_` | Custom Cabinets |
| `kitchen_` | Kitchens |
| `bath_` | Bathrooms |
| `reno_` | Renovations |
| `carp_` | Carpentry |
| `new_` | New Construction |
| `custom_` | Custom Work |
| `remodel_` | Renovations |
| `construction_` | New Construction |
| `outdoor_` | Outdoor Living |
| `patio_` | Outdoor Living |
| `interior_` | Interior Design |
| Any other name | Our Work |

### Examples

- `deck_custom_cedar_01.jpg` → "Custom Decks"
- `kitchen_remodel_2024.png` → "Kitchens"  
- `cabinet_built_in_01.jpg` → "Custom Cabinets"
- `project_completion.jpg` → "Our Work"

### Best Practices

**Recommended filename format:**
```
[category]_[brief-description]_[sequence].ext
```

Examples:
- `deck_cedar_patio_01.jpg`
- `kitchen_white_cabinets_01.jpg`
- `bath_master_suite_01.jpg`
- `carp_builtin_shelving_01.jpg`
- `new_home_trinity_01.jpg`

**Avoid:**
- Spaces in filenames (use underscores or hyphens)
- Special characters (!@#$%^&* etc.)
- Very long filenames

## File Structure

```
public_html/
├── assets/
│   └── gallery/                    # Put images here
│       ├── deck_cedar_01.jpg
│       ├── deck_composite_01.jpg
│       ├── kitchen_remodel_01.jpg
│       ├── bath_master_01.jpg
│       └── carp_cabinets_01.jpg
├── scan-gallery.js               # Auto-discovery script
├── gallery-data.json             # Generated data file
└── gallery.php                   # Gallery page
```

## Gallery Data File

The `gallery-data.json` file contains:

```json
{
  "generated": "2026-05-29T12:00:00.000Z",
  "totalImages": 15,
  "categories": {
    "Custom Decks": {
      "name": "Custom Decks",
      "slug": "custom-decks",
      "count": 5,
      "images": ["id1", "id2", "id3"]
    },
    "Kitchens": {
      "name": "Kitchens", 
      "slug": "kitchens",
      "count": 3,
      "images": ["id4", "id5", "id6"]
    }
  },
  "images": [
    {
      "id": "unique-hash-123",
      "filename": "deck_cedar_01.jpg",
      "path": "assets/gallery/deck_cedar_01.jpg",
      "url": "/assets/gallery/deck_cedar_01.jpg",
      "category": "Custom Decks",
      "categorySlug": "custom-decks",
      "title": "Deck Cedar 01",
      "description": "",
      "metadata": {
        "size": 123456,
        "modified": "2026-05-29T10:00:00.000Z"
      }
    }
  ]
}
```

## Updating the Gallery

### Adding Images

1. Add new images to `assets/gallery/`
2. Run: `node scan-gallery.js`
3. Refresh your gallery page - new images appear automatically

### Removing Images

1. Delete images from `assets/gallery/`
2. Run: `node scan-gallery.js`
3. Refresh your gallery page - removed images are gone

### Renaming Images

1. Rename the file in `assets/gallery/`
2. Run: `node scan-gallery.js`
3. The category and title will update automatically

## Advanced Usage

### Custom Image Information

To add custom titles, descriptions, or sort orders:

1. Edit the generated `gallery-data.json` file
2. Modify the specific image's properties
3. Save the file - changes appear immediately on the gallery page

Example modification:

```json
{
  "id": "unique-hash-123",
  "filename": "deck_cedar_01.jpg",
  "path": "assets/gallery/deck_cedar_01.jpg",
  "url": "/assets/gallery/deck_cedar_01.jpg",
  "category": "Custom Decks",
  "title": "Beautiful Cedar Deck in Trinity",
  "description": "400 sq ft custom cedar deck with built-in seating and lighting",
  "sortOrder": 1
}
```

### Automating the Process

You can set up a cron job to run the scan automatically (e.g., daily):

```bash
# Add to crontab (run: crontab -e)
0 2 * * * cd /home/HexNemesis/web/naileditconstruct.com/public_html/ && node scan-gallery.js
```

This runs the scan every day at 2:00 AM.

## Image Recommendations

### Quality Guidelines

- **Resolution:** Minimum 1200x800 pixels (higher is better)
- **Format:** JPEG for photos, PNG for graphics with transparency
- **Optimization:** Compress images for web (use tools like TinyPNG, ImageOptim)
- **Orientation:** Both landscape and portrait work well

### Content Tips

- Show completed projects from multiple angles
- Include close-ups of fine details (craftsmanship)
- Capture "before and after" shots when possible
- Use natural lighting for best results
- Keep backgrounds clean and uncluttered

## Supported Image Formats

| Format | Extension | Notes |
|--------|-----------|-------|
| JPEG | .jpg, .jpeg | Best for photos, smaller file size |
| PNG | .png | Supports transparency, larger files |
| WebP | .webp | Modern format, excellent compression |
| SVG | .svg | Vector graphics, scales perfectly |
| GIF | .gif | Animated images supported |

## Troubleshooting

### Images Not Appearing

1. **Check file extensions:** Ensure files have supported extensions
2. **Verify location:** Images must be in `assets/gallery/`
3. **Run scan:** Did you run `node scan-gallery.js` after adding images?
4. **Check permissions:** Ensure the script can read the directory
5. **Case sensitivity:** Some servers are case-sensitive - use lowercase extensions

### Common Issues

**Problem:** "Error: Cannot find module" when running scan-gallery.js

**Solution:** Ensure Node.js is installed. Run `node -v` to check. If not installed, download from [nodejs.org](https://nodejs.org/)

**Problem:** Images appear but with wrong categories

**Solution:** Rename files to include the correct prefix (e.g., `deck_` for deck images)

**Problem:** Gallery page shows loading error

**Solution:** Check that `gallery-data.json` exists and is valid JSON

## Integration with Gallery Page

The `gallery.php` page automatically loads `gallery-data.json` and displays images in a responsive grid with:

- Category filtering
- Lightbox/Modal viewing
- Image captions and details
- Responsive design for all devices

No manual changes to `gallery.php` are needed when adding new images.

## Backup and Version Control

### .gitignore Recommendation

Add this to your `.gitignore` if using Git:

```gitignore
# Gallery images
assets/gallery/

# Generated data
gallery-data.json

# Keep the scan script
!scan-gallery.js
```

### Manual Backup

Regularly backup your gallery images:

```bash
# Create a backup directory
mkdir -p /path/to/backup/gallery/$(date +%Y-%m-%d)

# Copy all gallery images
cp -r assets/gallery/* /path/to/backup/gallery/$(date +%Y-%m-%d)/
```

## Performance Tips

### Image Optimization

- **Compress images:** Use tools like:
  - [TinyPNG](https://tinypng.com/) (JPG/PNG)
  - [ImageOptim](https://imageoptim.com/) (Mac)
  - [Squoosh](https://squoosh.app/) (Web-based)

- **Resize images:** Use appropriate dimensions
  - Gallery thumbnails: 600-800px wide
  - Full-size images: 1200-2000px wide

### Lazy Loading

The gallery page uses lazy loading by default - images load as users scroll, improving page load times.

### CDN Integration

For high-traffic sites, consider using a CDN:
- AWS CloudFront
- Cloudflare
- BunnyCDN

## API Usage

If you want to programmatically access gallery data:

```javascript
// Load gallery data
fetch('/gallery-data.json')
  .then(response => response.json())
  .then(data => {
    console.log(`Found ${data.totalImages} images`);
    data.images.forEach(image => {
      console.log(`${image.title} (${image.category})`);
    });
  });
```

## Support

For questions or issues with the gallery system:

1. Check this README file first
2. Run `node scan-gallery.js --help` (if available)
3. Verify file permissions: `ls -la assets/gallery/`
4. Check for errors when running the script
5. Contact your web developer

## Technical Details

### Dependencies

The scan script requires:
- Node.js 12.x or higher
- No additional npm packages needed

### Script Commands

```bash
# Basic scan
node scan-gallery.js

# Check Node.js version
node -v

# Check if Node is installed
which node
```

### Output Format

The `gallery-data.json` follows this schema:

```typescript
interface GalleryImage {
  id: string;              // Unique MD5 hash
  filename: string;        // Original filename
  path: string;            // Relative path
  url: string;             // Full URL
  category: string;        // Auto-detected category
  categorySlug: string;    // URL-friendly category
  title: string;           // Formatted title
  description: string;     // Custom description (optional)
  metadata: {
    size: number;           // File size in bytes
    modified: string;       // Last modified date (ISO)
  };
  sortOrder: number;      // Custom sort order (default: 0)
}

interface GalleryData {
  generated: string;       // Generation timestamp (ISO)
  totalImages: number;     // Total image count
  categories: {
    [categoryName: string]: {
      name: string;
      slug: string;
      count: number;
      images: string[];     // Array of image IDs
    }
  };
  images: GalleryImage[];   // All images
}
```

## License

This gallery system is provided as-is for use with Nailed It Construction. The code is free to use and modify.

## Credits

- Built with Node.js
- Uses modern JavaScript (ES6+)
- Compatible with all modern browsers

---

**Last Updated:** May 29, 2026
**Version:** 1.0.0