# Architecture Redesign Proposal

## The Problem (Current State)

**Duplication:**
```
home/index.md          ← OLD (not used)
home/index.json        ← GENERATED
content/home/index.md  ← SOURCE (new)

home/footer.md         ← ORPHANED
home/footer.html       ← ORPHANED
```

**Assets scattered:**
- `/german/` contains: index.md, index.json, PDFs, PNGs
- Referenced in markdown: `![img](/german/file.png)`
- Results in: Assets mixed with content

**Duplication Result:** Extra folders, confusing structure, maintenance nightmare

---

## Proposed Solution: Single Source Structure

### Concept
```
Use ONLY /content/ as the source of truth
Everything else is generated or static assets
```

### New Structure

```
/public_html/
├── content/                 ← SOURCE OF TRUTH (only edit here!)
│   ├── home/
│   │   └── index.md
│   ├── projects/
│   │   └── index.md
│   ├── blog/
│   │   ├── index.md
│   │   ├── post1.md
│   │   └── post2.md
│   ├── german/
│   │   ├── index.md
│   │   ├── Mittelpunkt_neu_B2_Lehrbuch.pdf    ← Assets stay here
│   │   ├── gv.png
│   │   ├── anki.png
│   │   └── wordle.png
│   ├── files/
│   │   └── index.md
│   ├── about/
│   │   └── index.md
│   ├── pics/
│   │   └── index.md
│   └── _shared/              ← OPTIONAL: shared assets
│       └── common-image.png
│
├── public/                  ← GENERATED (don't edit!)
│   ├── home/
│   │   └── index.json
│   ├── projects/
│   │   └── index.json
│   ├── blog/
│   │   ├── index.json
│   │   ├── post1.json
│   │   └── post2.json
│   └── german/
│       └── index.json        ← ONLY JSON, not assets
│
├── index.php                ← MAIN (unchanged)
├── rebuild.sh               ← REBUILD SCRIPT (updated)
├── generate_json.php        ← GENERATOR (updated)
├── watch.php                ← WATCHER (updated)
└── .htaccess                ← REWRITES public/ → /
```

### Why This Works

1. **Single source:** Edit only `/content/`
2. **Clear separation:** 
   - Assets: `/content/section/file.pdf` (you edit/add these)
   - Generated JSON: `/public/section/index.json` (auto-generated)
3. **No duplication:** No old folders to confuse
4. **Assets accessible:** When markdown references `/german/file.png`, .htaccess serves it from `/content/german/file.png`
5. **Easy to maintain:** Folder structure mirrors the site structure

---

## Implementation Plan

### Phase 1: Prepare

1. **Create `/public/` directory:**
   ```bash
   mkdir -p public
   ```

2. **Keep `/content/` structure (no changes needed)**

3. **Delete old folders** (backup first):
   ```bash
   # These will no longer be needed
   rm -rf home/ blog/ projects/ about/ german/ files/ pics/
   # (keep the backup if you want)
   ```

### Phase 2: Update .htaccess

**Current .htaccess:** (no routing needed)

**New .htaccess:**
```apache
<IfModule mod_rewrite.c>
    RewriteEngine On
    
    # Serve content assets directly (images, PDFs, etc)
    # If file exists in content/, serve it
    RewriteCond %{REQUEST_URI} !^/index\.php$
    RewriteCond /home/jisifu/public_html/content%{REQUEST_URI} -f
    RewriteRule ^(.+)$ /content/$1 [L]
    
    # JSON files come from public/
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)/$ /public/$1/index.json [L]
</IfModule>

<IfModule mod_deflate.c>
    AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript
</IfModule>

<IfModule mod_expires.c>
    ExpiresActive On
    
    # Don't cache JSON files (they change frequently)
    ExpiresByType application/json "now"
    
    # Cache static assets longer
    ExpiresByType text/css "access plus 1 month"
    ExpiresByType application/javascript "access plus 1 month"
    ExpiresByType image/* "access plus 1 year"
    ExpiresByType font/* "access plus 1 year"
    ExpiresByType application/pdf "access plus 1 year"
</IfModule>
```

### Phase 3: Update generate_json.php

```php
<?php
require_once 'lib/ContentRenderer.php';
require_once 'lib/ContentManager.php';

$renderer = new ContentRenderer();
$manager = new ContentManager('content/');

echo "Generating JSON files...\n\n";

// Ensure public/ exists
if (!is_dir('public')) {
    mkdir('public', 0755, true);
}

// Generate section JSON files
$sections = $manager->getSections();
foreach ($sections as $section_name => $section) {
    $content = $manager->getSection($section_name);
    if ($content) {
        $html = $renderer->render($content['content']);
        $json = json_encode([
            'section' => [
                'innerHTML' => $html
            ]
        ]);
        
        // Output to public/ instead
        $output_dir = "public/$section_name";
        if (!is_dir($output_dir)) {
            mkdir($output_dir, 0755, true);
        }
        
        file_put_contents("$output_dir/index.json", $json);
        echo "✓ public/$section_name/index.json\n";
    }
}

// Similar changes for blog posts...
// (change blog/{$post['name']}.json to public/blog/{$post['name']}.json)

echo "\n✓ Done!\n";
?>
```

### Phase 4: Update index.php

Just update the fetch URLs to use `/public/`:

```php
fetch('/public/home/index.json?t=' + Date.now())
```

### Phase 5: Update rebuild.sh

```bash
#!/bin/bash
cd "$(dirname "$0")" || exit 1
echo "Generating JSON files to public/..."
php generate_json.php
if [ $? -eq 0 ]; then
    echo ""
    echo "✓ Complete! Visit your site to see changes."
else
    echo ""
    echo "✗ Error during generation"
    exit 1
fi
```

---

## File Location Strategy

### Content Assets
Place in `/content/section/` folder where the markdown is:

```
content/german/
├── index.md                          ← Edit this
├── Mittelpunkt_neu_B2_Lehrbuch.pdf  ← Reference as /german/file.pdf
├── gv.png                            ← Reference as /german/gv.png
└── anki.png
```

In your markdown:
```markdown
![img](/german/gv.png)
[PDF](/german/Mittelpunkt_neu_B2_Lehrbuch.pdf)
```

The .htaccess will serve these directly from `/content/german/`.

### How Asset Serving Works

```
User requests: GET /german/gv.png
     ↓
Apache .htaccess rule:
  "If /content/german/gv.png exists, serve it"
     ↓
File served from: /content/german/gv.png
     ↓
User sees: /german/gv.png
```

Transparent!

---

## Benefits of This Design

| Aspect | Before | After |
|--------|--------|-------|
| **Source folders** | Multiple (content/, home/, blog/, etc.) | Single (`content/`) |
| **Asset location** | Mixed with JSON | In `content/` with markdown |
| **Generated files** | Scattered in folders | Organized in `public/` |
| **Rebuilds** | Overwrites everything | Only touches `public/` |
| **Cleanup** | Delete multiple folders | Delete just `public/` and rebuild |
| **Clarity** | Confusing duplication | Clear: edit `content/`, auto-generates `public/` |

---

## Progressive Enhancement Path

Your insight: "I like markdown → JSON → PHP because later I can alter JSON to do more reactive things"

With this structure, you can easily:

1. **Phase 1 (Now):** Markdown → JSON → PHP (server renders)
2. **Phase 2:** Add data to JSON beyond just `innerHTML`
   ```json
   {
     "section": {
       "innerHTML": "...",
       "title": "German Course",
       "updated": "2026-02-12",
       "author": "jisifu"
     }
   }
   ```

3. **Phase 3:** JavaScript enhances with client-side reactivity
   ```javascript
   const data = await fetch('/public/german/index.json').then(r => r.json());
   // Now you can use data.section.title for dynamic titles
   // Use data.section.updated for timestamps
   // Add interactive features without reloading
   ```

4. **Phase 4:** Add structured data (JSONLD for SEO, etc.)
   ```json
   {
     "section": { "innerHTML": "..." },
     "metadata": {
       "type": "BlogPost",
       "title": "...",
       "datePublished": "..."
     }
   }
   ```

The JSON structure grows with you!

---

## Migration Steps (Safe & Reversible)

1. **Backup first:**
   ```bash
   mkdir backup
   cp -r home/ blog/ projects/ about/ german/ files/ pics/ backup/
   ```

2. **Create public/ directory:**
   ```bash
   mkdir public
   ```

3. **Update .htaccess** (carefully, or keep old one as backup)

4. **Update generate_json.php** (test in dev first)

5. **Run rebuild:**
   ```bash
   ./rebuild.sh
   ```

6. **Test thoroughly:**
   - Check all pages load
   - Check all assets load (images, PDFs)
   - Check console for errors

7. **Delete old folders** (only after testing):
   ```bash
   rm -rf home/ blog/ projects/ about/ german/ files/ pics/
   ```

---

## Alternative: Keep It Simpler (Minimal Change)

If you prefer fewer changes, just:

1. Keep current structure (don't create `public/`)
2. Clean up the OLD markdown files (home/index.md → delete)
3. Keep generating to current directories
4. Result: Same as now, but cleaner

**Pros:** Minimal changes
**Cons:** Still has duplication (content/ + current dirs)

---

## My Recommendation

**Go with the "Single Source" design** because:

1. ✅ Eliminates duplication
2. ✅ Asset location clear (`content/section/`)
3. ✅ Generated files organized (`public/`)
4. ✅ Scales well for future enhancements
5. ✅ Still simple and maintainable
6. ✅ Sets you up for progressive enhancement

**Implementation effort:** ~2 hours work to:
- Create public/ structure
- Update 2-3 files (.htaccess, generate_json.php, index.php)
- Test everything
- Delete old folders

---

## Summary

Current: Confusing duplication (content/ + home/ + blog/ + ...)
Proposed: Clear separation (content/ = source, public/ = generated)

Edit: `/content/` (markdown + assets)
Generated: `/public/` (JSON only)
Served: Files transparent to user

Would you like me to implement this refactor?