# Website Refactoring - New Architecture

## Overview

I've refactored your website from a **client-side JSON-driven system** to a **server-side rendered system with progressive enhancement**. Here's what changed and why.

## What You Had

Your original system was clever:
```
Markdown → build.nu → JSON files → index.php sidebar
                                 → fetch JSON
                                 → JavaScript injects HTML
```

**Problems:**
- JavaScript required to see content
- Content not in initial HTML (worse SEO)
- Extra JSON files to maintain
- Complex JavaScript needed to manage state

## What You Have Now

```
Markdown files → PHP router → HTML renderer → Full page sent to browser
                                          → Optional: Progressive enhancement
```

**Benefits:**
- ✅ Works without JavaScript
- ✅ Content in initial HTML (better SEO)
- ✅ No build step needed!
- ✅ Simpler, fewer files
- ✅ Faster initial page load
- ✅ Server-side caching support

## Quick Start

### The System Works Right Now

1. **Visit your site normally** - all content is there
2. **Click sidebar links** - they work!
3. **Check the source** - full HTML is in the page

No changes needed to your content!

### Adding New Content

**Before (required build step):**
```bash
# 1. Create markdown
# 2. Run build.nu
# 3. Wait for JSON generation
# 4. Hope JavaScript didn't break
```

**Now (just create files):**
```bash
# Create a blog post
echo "# My Blog Post" > content/blog/my-awesome-post.md
echo "Content here..." >> content/blog/my-awesome-post.md

# Done! Visit http://your-site/blog/my-awesome-post
# No build needed!
```

## File Structure

### New Files

```
lib/
├── ContentRenderer.php    - Converts markdown → HTML
└── ContentManager.php     - Finds and lists content

partials/
├── sidebar.php           - Navigation menu
├── footer.php            - Footer
└── wasm.html            - WASM components (if needed)

js/
└── enhance.js           - Optional smooth transitions

router.php                - Central request handler
template.php              - Base HTML layout
.htaccess                 - URL rewriting
```

### New Directory

```
content/
├── home/index.md
├── projects/index.md
├── blog/
│   ├── post1.md
│   ├── post2.md
│   └── fibonacci_tree.md
└── ...
```

### Updated

```
index.php                 - Now just includes router.php
build.nu                  - Simplified (validation only)
```

## How It Works

### Simple Example: Visiting `/blog`

1. **Browser requests**: `GET /blog`
2. **Apache** (.htaccess): "Not a real file → send to router.php"
3. **router.php**:
   - Parses path: "blog"
   - Calls `ContentManager::getSection('blog')`
   - Gets markdown content
4. **ContentRenderer**:
   - Runs `comrak` to convert markdown → HTML
   - Caches result (optional)
5. **template.php**:
   - Renders full page HTML
   - Includes entire content
6. **JavaScript** (enhance.js):
   - Adds smooth transitions
   - Prefetches on hover
   - Updates URL without reload
   - **Works only if enabled** - page already works without it

## Key Components

### ContentRenderer.php

Converts markdown to HTML using comrak:

```php
$renderer = new ContentRenderer($use_file_cache = false);
$html = $renderer->renderFile('content/blog/my-post.md');
```

Features:
- Memory caching
- Optional file caching
- Error handling

### ContentManager.php

Finds and organizes content:

```php
$manager = new ContentManager('content/');

// Get all sections
$sections = $manager->getSections();
// ['home' => [...], 'blog' => [...], ...]

// Get a specific page
$page = $manager->getSection('about');
// ['title' => '...', 'content' => '...']

// Get all blog posts
$posts = $manager->getBlogPosts();
// [['title' => '...', 'path' => '...'], ...]
```

### router.php

Handles URL routing:

- `/` → home section
- `/about` → about section
- `/blog` → blog listing
- `/blog/my-post` → specific blog post
- `/unknown` → 404 page

### template.php

Base HTML template:

- Includes CSS/meta tags
- Renders sidebar
- Renders content
- Includes enhance.js

### enhance.js

Progressive enhancement (optional):

- Smooth fade transitions
- Prevents full page reloads
- Prefetches pages on hover
- Updates browser history
- **All of this is optional** - everything works without it

## Performance Characteristics

| Metric | Before | After |
|--------|--------|-------|
| **Initial Load** | HTML + JS needed to fetch JSON | Full HTML in response |
| **Time to Content** | Slower (fetch + render) | Faster (direct in HTML) |
| **Navigation** | JS required | Works with or without JS |
| **SEO** | Limited (content in DOM but JS-dependent) | Excellent (content in HTML) |
| **Caching** | Browser cache only | Server-side caching available |

## Customization

### Add a New Section

Just create a markdown file:

```bash
mkdir -p content/mynewsection
echo "# My New Section" > content/mynewsection/index.md
```

The system automatically discovers it!

### Add a Blog Post

```bash
echo "# Post Title" > content/blog/my-post.md
```

Automatically appears in blog listing!

### Change Layout

Edit `template.php`:
- Add CSS classes
- Rearrange sidebar
- Modify page structure

### Change Sidebar

Edit `partials/sidebar.php`:
- Reorder sections
- Add icons
- Custom styling

### Enable Caching

In `router.php`:
```php
$renderer = new ContentRenderer($use_file_cache = true);
```

Creates `cache/` directory with compiled HTML.

### Customize Progressive Enhancement

Edit `js/enhance.js`:
- Change transition speed
- Disable preloading
- Add analytics
- Custom routing

## Migration Checklist

- [x] Created new library files (ContentRenderer, ContentManager)
- [x] Created router and template
- [x] Created partial templates
- [x] Created progressive enhancement script
- [x] Created `.htaccess` for routing
- [x] Created `content/` directory
- [x] Copied all markdown files
- [x] Updated `build.nu`
- [x] Updated `index.php`

**To complete the migration:**

1. ✅ Test in browser - verify all pages work
2. ✅ Check that links work
3. ✅ Verify sidebar updates correctly
4. ✅ Try adding a new page
5. ⚠️ Archive old files (keep as backup):
   ```bash
   mkdir -p /backup
   cp *.json /backup/
   cp */index.json /backup/
   ```
6. ⚠️ Monitor error logs for a few days

## Troubleshooting

### "404 Not Found" on pages

**Check:**
1. Is `.htaccess` enabled? (Ask hosting provider)
2. Does `content/section/index.md` exist?
3. Check PHP error log: `/var/log/apache2/error.log`

**Test:**
```bash
# Directly access router
curl http://your-site/router.php
```

### JavaScript not enhancing smoothly

**Check:**
1. Open browser console (F12)
2. Look for errors
3. Check that `js/enhance.js` is loading

**Note:** This is okay! The site still works without JS.

### Old files still showing

**Clear:**
1. Browser cache (Ctrl+Shift+Delete)
2. Server cache (if enabled): `$renderer->clearCache()`
3. CDN cache (if used)

## Files to Archive (Not Delete!)

Keep backups of these old files:

```
.backup/
├── index_old.php
├── home/index.json
├── blog/*.json
├── about/index.json
└── ... (all old JSON files)
```

You can delete them after 1-2 weeks if everything works.

## Optional: Update build.nu

The new `build.nu` is simplified. It just validates the structure:

```bash
nu build.nu
```

This generates a `sitemap.json` for reference. You don't need to run this for the site to work - it's just useful for your own records.

## Advanced: Caching Strategy

For high-traffic sites, enable file caching:

```php
// In router.php
$renderer = new ContentRenderer($use_file_cache = true);
```

Cache invalidation:
```php
// When you update content
$renderer->clearCache();
```

Cache location: `cache/` directory

## Advanced: Database (Future)

If you need more complex data, you can:

1. Keep using markdown files (simple)
2. Add SQLite for searchable content
3. Add a JSON API for AJAX operations
4. Extend ContentManager to read from multiple sources

The system is designed to be extended!

## FAQ

### Do I need to run build.nu?

No! The new system renders on-demand. Running `build.nu` is optional - it just generates a sitemap for your reference.

### Can I keep the old files?

Yes, during migration. Archive them in a backup directory. Delete after testing thoroughly.

### Does JavaScript need to work?

No! The site works perfectly without it. JavaScript just adds smooth transitions - it's a progressive enhancement.

### Can I cache the rendered pages?

Yes! Enable in router.php: `$renderer = new ContentRenderer(true)`

### How do I update the sidebar?

Edit `partials/sidebar.php`. Sections are automatically discovered from `content/` directory.

### Can I add dynamic content?

Yes! You can modify ContentManager to:
- Read from a database
- Fetch from an API
- Generate dynamic content
- All while keeping the same interface

## Next Steps

1. **Test thoroughly**
   - Visit each page
   - Click all links
   - Try JavaScript disabled (F12 → Network → Offline)

2. **Add new content**
   - Create `content/newsection/index.md`
   - See it appear in sidebar
   - No build step!

3. **Customize**
   - Edit `template.php` for layout
   - Edit `partials/` for components
   - Edit `js/enhance.js` for behavior

4. **Monitor**
   - Check error logs
   - Track performance
   - Gather user feedback

## Support

Files with documentation:
- `ARCHITECTURE.md` - Design decisions
- `MIGRATION.md` - Step-by-step migration
- Comments in PHP files - Implementation details

Code is well-commented for future reference.

---

## Summary

Your website now:
- ✅ Renders on the server (better performance)
- ✅ Works without JavaScript
- ✅ Supports progressive enhancement
- ✅ Requires no build step for new content
- ✅ Is easier to understand and modify
- ✅ Has better caching options
- ✅ Follows web standards

The core principle: **Server renders HTML, JavaScript enhances if available.**

This is the modern approach to building reliable, fast, accessible websites!