# Website Architecture Analysis & Refactoring Guide ## Current Architecture Overview Your system is a clever **isomorphic hybrid** combining: - **Backend**: PHP dynamic routing + directory listing - **Build-time**: Nushell (`build.nu`) compiles Markdown → JSON - **Frontend**: Single ` ``` ### Phase 2: Content Rendering Library **New `lib/ContentRenderer.php`:** ```php ['pipe', 'r'], 1 => ['pipe', 'w'], ], $pipes); fwrite($pipes[0], $markdown); fclose($pipes[0]); $html = stream_get_contents($pipes[1]); fclose($pipes[1]); proc_close($proc); self::$cache[$cacheKey] = $html; return $html; } } ?> ``` ### Phase 3: Sidebar as PHP **New `partials/sidebar.php`:** ```php ``` ### Phase 4: Blog Index Generation (Enhanced Build Script) **Simplified `build.nu`:** ```nushell # Build blog index let blog_posts = (glob blog/*.md | each {|f| { name: ($f | path parse | get stem) title: (open $f | lines | first | str replace "# " "") date: (ls $f | get modified.0) } } | sort-by date -r ) # Generate blog index.md with listing let index = $"# Blog\n\n" + ($blog_posts | each {|p| $"- [$p.title](/blog/$p.name)" } | str join "\n") $index | save blog/index.md ``` ### Phase 5: Progressive Enhancement (Minimal JS) **New `public/js/enhance.js`:** ```javascript // Progressive enhancement: prefetch & smooth transitions document.querySelectorAll('[data-section]').forEach(link => { link.addEventListener('click', async (e) => { e.preventDefault(); const section = e.target.dataset.section; const response = await fetch(`/?section=${section}`); const html = await response.text(); // Replace main content const parser = new DOMParser(); const doc = parser.parseFromString(html, 'text/html'); document.querySelector('main').innerHTML = doc.querySelector('main').innerHTML; // Update URL without reload history.pushState(null, '', `/${section}`); }); }); ``` ## Advantages of New Architecture | Aspect | Before | After | |--------|--------|-------| | **Initial Load** | JS-dependent | Full HTML in response | | **Caching** | Relies on browser | Can add Server caching | | **SEO** | Content in DOM but lazy | Content in initial HTML | | **Adding content** | Update Nu + JS + HTML | Just add `.md` file | | **Performance** | Extra JSON requests | Eliminate round-trips | | **Accessibility** | Partially dependent on JS | Works without JS | | **Debugging** | Check network, DOM, JS | View source | ## Implementation Path 1. **Create `lib/ContentRenderer.php`** - Test markdown rendering 2. **Create `router.php`** - Handle routing logic 3. **Create `template.php`** - Base layout 4. **Create `partials/`** - Sidebar, footer, etc. 5. **Refactor `build.nu`** - Simplify to just markdown organization 6. **Move content** - Organize markdown files 7. **Add `enhance.js`** - Progressive enhancement 8. **Test** - Verify all pages work ## Caching Strategy (Optional, Phase 2) For better performance, add optional caching: ```php cache_dir . hash('sha256', $key); if (file_exists($file)) { return file_get_contents($file); } return null; } public function set($key, $content) { file_put_contents( $this->cache_dir . hash('sha256', $key), $content ); } } ?> ``` ## Database Alternative (If You Scale) If you add many features, consider: - **SQLite** for simple storage (no server setup) - **JSON files** remain for version control - **PHP reads** from either source ```php query('SELECT * FROM posts ORDER BY date DESC'); ?> ``` ## Backward Compatibility You can implement this incrementally: 1. Keep `index.php` working while adding new router 2. Serve both old and new endpoints 3. Migrate sidebar links gradually 4. Remove old system once confident --- ## Summary Your original idea was solid—now we're making it: - ✅ Server-rendered (better SEO/accessibility) - ✅ Simpler to understand and modify - ✅ Easier to add caching - ✅ Still supports progressive enhancement - ✅ Better separation of concerns Want me to help implement any of these phases?