╔══════════════════════════════════════════════════════════════════════════╗
║                    WEBSITE ARCHITECTURE DIAGRAM                          ║
╚══════════════════════════════════════════════════════════════════════════╝


┌─────────────────────────────────────────────────────────────────────────┐
│                         REQUEST FLOW                                     │
└─────────────────────────────────────────────────────────────────────────┘

    Browser Request
         ↓
    GET /blog
         ↓
    ┌─────────────────────┐
    │   Apache/Server     │
    │  (.htaccess rules)  │
    └────────┬────────────┘
             ↓
    Is it a real file?
      YES → Serve it
      NO  → router.php
             ↓
    ┌─────────────────────────────────┐
    │      router.php                 │
    │  - Parse URL path               │
    │  - Determine section/page       │
    │  - Handle routing logic         │
    └────────┬────────────────────────┘
             ↓
    ┌──────────────────────────────────────┐
    │    ContentManager                    │
    │  - Find content/section/index.md     │
    │  - Read markdown file               │
    │  - Extract title and content        │
    └────────┬─────────────────────────────┘
             ↓
    ┌──────────────────────────────────────┐
    │    ContentRenderer                   │
    │  - Run comrak (markdown → HTML)      │
    │  - Cache result (optional)           │
    │  - Return HTML                       │
    └────────┬─────────────────────────────┘
             ↓
    ┌──────────────────────────────────────┐
    │      template.php                    │
    │  - Render full page HTML             │
    │  - Include sidebar.php               │
    │  - Include footer.php                │
    │  - Inject rendered content           │
    │  - Include enhance.js                │
    └────────┬─────────────────────────────┘
             ↓
    Complete HTML Page (with content already in DOM)
             ↓
    Browser Renders Page
             ↓
    enhance.js (if JavaScript enabled)
    - Add click handlers to links
    - Enable smooth transitions
    - Prefetch pages on hover


┌─────────────────────────────────────────────────────────────────────────┐
│                        DIRECTORY STRUCTURE                               │
└─────────────────────────────────────────────────────────────────────────┘

public_html/
│
├── index.php                    ← Entry point (includes router.php)
├── router.php                   ← Request router
├── template.php                 ← Base HTML template
├── test.php                     ← Test suite
│
├── .htaccess                    ← URL rewriting rules
│
├── lib/
│   ├── ContentRenderer.php      ← Markdown → HTML conversion
│   └── ContentManager.php       ← Content discovery & organization
│
├── partials/
│   ├── sidebar.php              ← Navigation menu
│   ├── footer.php               ← Footer content
│   └── wasm.html                ← WASM components (optional)
│
├── js/
│   └── enhance.js               ← Progressive enhancement
│
├── content/                     ← All markdown content
│   ├── home/
│   │   └── index.md
│   ├── projects/
│   │   └── index.md
│   ├── blog/
│   │   ├── fibonacci_tree.md
│   │   ├── htmz.md
│   │   └── nublog.md
│   ├── about/
│   │   └── index.md
│   ├── files/
│   │   └── index.md
│   ├── german/
│   │   └── index.md
│   └── pics/
│       └── index.md
│
└── cache/                       ← Optional: Cached HTML (if enabled)


┌─────────────────────────────────────────────────────────────────────────┐
│                    REQUEST HANDLING EXAMPLES                             │
└─────────────────────────────────────────────────────────────────────────┘

Example 1: User visits /blog
─────────────────────────────

1. Browser:   GET /blog
2. Apache:    Redirect to router.php
3. router.php:
   - $section = 'blog'
   - Calls $manager->getBlogPosts()
   - Creates blog index markdown
   - Renders with ContentRenderer
4. template.php:
   - Renders full page
   - Sidebar shows "blog" as active
   - Content shows post listing
5. Browser:   Full page with blog list


Example 2: User visits /blog/htmz
──────────────────────────────────

1. Browser:   GET /blog/htmz
2. Apache:    Redirect to router.php
3. router.php:
   - $section = 'blog'
   - $subsection = 'htmz'
   - Calls $manager->getBlogPost('htmz')
   - Gets content/blog/htmz.md
4. ContentRenderer:
   - Runs: echo "file content" | comrak --gfm --unsafe
   - Caches HTML
5. template.php:
   - Renders full page
   - Sidebar shows "blog" as active
   - Content shows the blog post
6. Browser:   Full page with blog post content


Example 3: User adds new blog post
───────────────────────────────────

1. User creates: content/blog/new-post.md
2. No rebuild needed!
3. Next request to /blog:
   - ContentManager runs: glob content/blog/*.md
   - Automatically discovers new post
   - Displays in blog listing
4. User can visit: /blog/new-post
   - System finds the markdown file
   - Renders and displays it


┌─────────────────────────────────────────────────────────────────────────┐
│                    JAVASCRIPT ENHANCEMENT FLOW                           │
└─────────────────────────────────────────────────────────────────────────┘

If JavaScript is Disabled:
──────────────────────────
    Click link → Browser navigates → Full page reload
    (Site works perfectly fine!)

If JavaScript is Enabled:
─────────────────────────
    Click link
        ↓
    enhance.js intercepts click
        ↓
    Fetch page via AJAX
        ↓
    Parse response
        ↓
    Update DOM (main content)
        ↓
    Update browser URL (history.pushState)
        ↓
    No full reload!
        ↓
    Smooth transition effect
        ↓
    User sees instant navigation


┌─────────────────────────────────────────────────────────────────────────┐
│                      CONTENT DISCOVERY FLOW                              │
└─────────────────────────────────────────────────────────────────────────┘

User creates: content/mynewpage/index.md
        ↓
ContentManager::getSections()
        ↓
glob content/*/
        ↓
Check for index.md in each directory
        ↓
Extract title from first # heading
        ↓
Build sections array
        ↓
sidebar.php displays them
        ↓
User sees new page in navigation!


┌─────────────────────────────────────────────────────────────────────────┐
│                       CACHING ARCHITECTURE                               │
└─────────────────────────────────────────────────────────────────────────┘

Without File Caching (Default):
───────────────────────────────
    Request
        ↓
    Check memory cache
        ↓
    Not found? Run comrak
        ↓
    Store in memory
        ↓
    Return HTML
    
    (Fast for repeated requests in same process)


With File Caching (Optional):
─────────────────────────────
    Request
        ↓
    Check memory cache
        ↓
    Not found? Check file cache
        ↓
    Not found? Run comrak
        ↓
    Save to file cache (cache/)
        ↓
    Store in memory
        ↓
    Return HTML
    
    (Persists across server restarts)


┌─────────────────────────────────────────────────────────────────────────┐
│                        ERROR HANDLING                                    │
└─────────────────────────────────────────────────────────────────────────┘

Content Not Found
    ↓
ContentManager returns null
    ↓
router.php sets 404 status
    ↓
Renders error content
    ↓
template.php includes it
    ↓
Browser sees friendly 404 page


Markdown File Missing
    ↓
file_get_contents() fails
    ↓
router.php catches error
    ↓
Renders "Not Found" message
    ↓
Returns to user

Comrak Not Installed
    ↓
proc_open() fails
    ↓
ContentRenderer catches it
    ↓
Returns error message
    ↓
User sees error (not blank page)


┌─────────────────────────────────────────────────────────────────────────┐
│                    BEFORE vs AFTER COMPARISON                            │
└─────────────────────────────────────────────────────────────────────────┘

BEFORE (JSON-driven system):
──────────────────────────

Browser Request
    ↓
Load index.php
    ↓
Load HTML with JavaScript
    ↓
JavaScript executes
    ↓
Fetch JSON file
    ↓
Parse JSON
    ↓
Inject innerHTML
    ↓
Content visible (after JS runs!)

Problems:
  ✗ Slow (needs JS execution)
  ✗ Content not in HTML (bad SEO)
  ✗ Doesn't work without JS
  ✗ Needs JSON files
  ✗ Complex JavaScript


AFTER (Server-rendered system):
────────────────────────────────

Browser Request
    ↓
router.php handles it
    ↓
Get markdown
    ↓
Render HTML
    ↓
Send full page
    ↓
Content visible immediately!

Benefits:
  ✓ Fast (no JS needed)
  ✓ Content in HTML (great SEO)
  ✓ Works without JS
  ✓ No JSON files
  ✓ Simple, clean code
  ✓ Optional JS enhancement


┌─────────────────────────────────────────────────────────────────────────┐
│                    DEPLOYMENT CONSIDERATIONS                             │
└─────────────────────────────────────────────────────────────────────────┘

Requirements:
  ✓ PHP 7.0+ (probably have this)
  ✓ Apache with mod_rewrite enabled (.htaccess support)
  ✓ comrak installed (Markdown processor)

Check:
  $ comrak --version
  $ php --version
  $ apache2ctl -M | grep rewrite

If comrak not installed:
  $ apt-get install comrak
  or
  $ brew install comrak


┌─────────────────────────────────────────────────────────────────────────┐
│                         SUMMARY                                          │
└─────────────────────────────────────────────────────────────────────────┘

The new system:

1. Receives HTTP request
2. Routes through router.php
3. Finds markdown content
4. Renders to HTML using comrak
5. Sends full page to browser
6. JavaScript (optional) enhances with smooth transitions

Result:
  ✅ Faster
  ✅ More accessible
  ✅ Better SEO
  ✅ Easier to maintain
  ✅ No build step needed

Simple, elegant, effective!