# Architecture

## System Overview
The application uses a hybrid architecture:
1. Server-side rendering for initial page load.
2. Client-side AJAX fragment swaps for navigation after first load.

## High-Level Components
1. Router and shell: `templ.php`
2. Shared UI includes: `sidebar.php`, `header.php`, `footer.php`
3. Content fragments: `mainContent.php`, `content2.php`, `online.php`
4. Frontend behavior: `assets/app.js`
5. Global styling: `assets/app.css`

## Request Flow
1. Browser requests `templ.php?page=<key>`.
2. `templ.php` sanitizes page key and resolves page file from whitelist.
3. If full request: render full HTML shell and include target page fragment.
4. If AJAX request (`ajax=1` or `X-Requested-With`): return fragment only.
5. `assets/app.js` injects returned HTML into `#content-area`, updates history, title, breadcrumb, and nav state.

## Routing Model
1. Whitelist-based route map in `resolveContentFile()`.
2. Unknown routes:
   - AJAX: returns 404 fragment.
   - Full page: falls back to `mainContent`.

## Client Runtime Model
1. `window.App` exposes shared utilities:
   - `App.navigate(page, label)`
   - `App.spinner` helper
   - `App.toast` helper
2. Event delegation handles clicks for elements with `data-page`.
3. `popstate` handler reloads fragment for browser history navigation.

## UI Composition
1. Sidebar defines nav hierarchy and per-link `data-page` / `data-label`.
2. Header defines toolbar, breadcrumb, and fullscreen toggle.
3. Footer defines app metadata and utility links.
4. Content pages are independent fragments with local script blocks.

## Data Model
Current data is static/demo arrays inside page fragments. No persistent storage layer is implemented.

## Architecture Risks
1. Route registry centralized in one file can become a maintenance bottleneck.
2. Inline script blocks in fragments can duplicate behavior and complicate testability.
3. No formal module boundaries in frontend JS beyond IIFE and object exposure.