# Architecture Reference

## Scope
This document describes the current runtime architecture, request flow, and structural risks.

## How To Use This File
1. Use this for design decisions and impact analysis before implementation changes.
2. Pair with [docs/PROGRAMMER_GUIDE.md](PROGRAMMER_GUIDE.md) for implementation workflow.
3. Update this file whenever component boundaries or request flow change.

## 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. Full request renders shell and includes the target content fragment.
4. AJAX request (`ajax=1` or `X-Requested-With`) returns fragment HTML only.
5. `assets/app.js` injects fragment into `#content-area`, then updates history, title, breadcrumb, and nav state.

## Routing Model
1. Route resolution uses an explicit metadata registry in `routes.php`.
2. Route metadata includes page file, navigation label, page title, and admin-only hint.
2. Unknown routes:
   - AJAX mode returns 404 fragment.
   - Full-page mode renders `error404` with HTTP 404.

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

## UI Composition
1. Sidebar defines nav hierarchy with `data-page` and `data-label`.
2. Header defines toolbar controls, breadcrumb, and fullscreen behavior.
3. Footer defines app metadata and utility links.
4. Content pages are fragment files rendered into `#content-area`.

## Data Model
Current data is static/demo arrays in fragment files. No persistent data layer is implemented.

## Architecture Risks
1. Centralized route registry can become a maintenance bottleneck.
2. Inline scripts in fragment files can duplicate behavior and reduce testability.
3. Frontend module boundaries are lightweight and depend on naming discipline.

## Architecture Change Checklist
- [ ] Routing changes reflected in architecture and programmer docs.
- [ ] New shared UI responsibilities documented.
- [ ] Runtime state changes and history behavior validated.
- [ ] Risks and trade-offs updated.