# Aki Framework Optimizations

## Overview
Optimizations made to the Aki-based PHP framework to improve build performance while maintaining markdown authoring workflow.

## Changes Made

### 1. Incremental Builds (`generate_json.php`)
**Before:** Every build regenerated ALL JSON files regardless of changes.
**After:** Compares file modification times and skips unchanged files.

```php
// Skip if output is newer than source
if (file_exists($output_file) && filemtime($output_file) >= filemtime($source_file)) {
    echo "⊘ public/$section_name/index.json (unchanged)\n";
    $skipped++;
    continue;
}
```

**Impact:** Dramatically reduces build time for large sites with many content files.

### 2. File Content Caching (`lib/ContentManager.php`)
**Before:** Files were read multiple times (once for metadata, again for content).
**After:** Implemented `$file_cache` array to cache file contents.

```php
private function getFileContent(string $filepath): string {
    if (!isset($this->file_cache[$filepath])) {
        $this->file_cache[$filepath] = file_exists($filepath) 
            ? file_get_contents($filepath) 
            : '';
    }
    return $this->file_cache[$filepath];
}
```

**Impact:** Reduces I/O operations by ~50% during builds.

### 3. File Cache for Rendering (`generate_json.php`)
**Before:** `ContentRenderer` had file cache capability but wasn't used.
**After:** Enabled file cache in build script.

```php
$renderer = new ContentRenderer(true, 'cache/'); // Enable file cache
```

**Impact:** Comrak rendering results are cached to disk, speeding up repeated builds.

### 4. Fixed Array Key Warning (`lib/ContentManager.php`)
**Issue:** `array_filter()` preserves keys, causing undefined index warnings.
**Fix:** Added `array_values()` to re-index the array.

```php
$paragraphs = array_values(array_filter(explode("\n", $clean_content), ...));
```

### 5. JSON_UNESCAPED_SLASHES (`generate_json.php`)
**Improvement:** Added `JSON_UNESCAPED_SLASHES` flag to `json_encode()` for cleaner JSON output.

### 6. Cache Headers (`.htaccess`)
**Added:** Proper cache headers for static assets.

```
ExpiresByType application/json "access plus 1 hour"
ExpiresByType text/css "access plus 1 week"
ExpiresByType application/javascript "access plus 1 week"
ExpiresByType image/png "access plus 1 month"
```

**Impact:** Reduces server load and improves page load times for repeat visitors.

## Performance Improvements

| Metric | Before | After |
|--------|--------|-------|
| Full rebuild time | ~X seconds | ~X seconds (unchanged) |
| Incremental build | Full rebuild | Only changed files |
| File I/O operations | 2-3 per file | 1 per file |
| JSON cache | None | Disk-based |

## Maintaining Markdown Authoring

All optimizations preserve the markdown authoring workflow:
- Content remains in `content/*.md` files
- YAML front matter still supported
- Build process still generates JSON for Aki architecture
- No changes to `index.php` or JavaScript

## Usage

```bash
# Incremental build (default) - only rebuilds changed files
php generate_json.php

# Force rebuild all files
rm -rf public/ cache/
php generate_json.php

# Using rebuild.sh (if available)
./rebuild.sh
```

## Future Optimization Opportunities

1. **Batch comrak processing:** Process multiple files in a single comrak invocation
2. **Parallel builds:** Use `popen()` or similar for parallel rendering
3. **ETag support:** Add ETag headers for JSON files
4. **Content hash:** Use content hash instead of mtime for change detection