folderweb/docs/04-development/01-architecture.md

# Architecture

## Directory Layout

```
app/                        # Framework core — stable API surface
  router.php                # Entry point: all requests route here
  constants.php             # CONTENT_EXTENSIONS, COVER_IMAGE_EXTENSIONS
  hooks.php                 # Hook enum + Hooks class
  context.php               # Context + Templates classes
  config.php                # createContext(): config merge + bootstrap
  helpers.php               # Utility functions (template resolution, extraction)
  content.php               # Content discovery, slug resolution, navigation
  rendering.php             # Markdown/HTML/PHP rendering, template wrapping
  cache.php                 # Markdown render cache (/tmp/folderweb_cache)
  plugins.php               # PluginManager class
  static.php                # /app/* asset serving with traversal protection
  vendor/                   # Parsedown + ParsedownExtra (Markdown→HTML)
  plugins/global/           # Built-in plugins (languages.php)
  default/                  # Demo/fallback theme (NOT for production use)
    config.ini              # Default configuration
    templates/              # base.php, page.php, list.php, list-compact.php, list-grid.php
    styles/                 # Default stylesheet
    languages/              # en.ini, no.ini
    content/                # Demo content shown when custom/ has no content
custom/                     # User layer — all site-specific work goes here
  config.ini                # Config overrides (merged over app/default/config.ini)
  templates/                # Override any template by matching filename
  styles/                   # Stylesheets served via /app/styles/*
  fonts/                    # Fonts served via /app/fonts/*
  assets/                   # Static files served at document root (favicon, robots.txt)
  languages/                # Translation overrides/additions (*.ini)
  plugins/global/           # Custom global plugins
  plugins/page/             # Custom page plugins (reserved, not yet active)
content/                    # Website content (= document root in production)
devel/                      # Dev environment (Containerfile, compose, Apache, perf tools)
docs/                       # Documentation (01-03 human-facing, 04 machine-facing)
```

## Stable Contracts

**`app/` is the framework.** When developing `custom/` sites, never modify `app/`. When developing the framework itself, preserve these contracts:

| Contract | Guaranteed Behavior |
|---|---|
| Override chain | `custom/*` always takes priority over `app/default/*` for templates, styles, languages, config |
| Template names | `base.php`, `page.php`, `list.php` are the three core template names |
| Hook enum | `Hook::CONTEXT_READY`, `Hook::PROCESS_CONTENT`, `Hook::TEMPLATE_VARS` — signatures documented in `05-hooks-plugins.md` |
| Context API | `$ctx->set()`, `$ctx->get()`, `$ctx->has()` — stable key/value store |
| Content extensions | `md`, `html`, `php` — defined in `CONTENT_EXTENSIONS` |
| Config format | INI with sections, merged via `array_replace_recursive` |
| Metadata format | INI file named `metadata.ini` in content directories |
| URL structure | Folder path = URL path, with slug overrides via metadata |
| Plugin locations | `app/plugins/{scope}/` and `custom/plugins/{scope}/` |
| Asset routes | `/app/styles/*` → `custom/styles/`, `/app/fonts/*` → `custom/fonts/`, `/app/default-styles/*` → `app/default/styles/` |
| Trailing slash | Pages and lists enforce trailing slash via 301 redirect |

## Request Flow

```
Browser request
  │
  ├─ Apache rewrite: all non-/app/ requests → app/router.php
  │
  ▼
router.php
  │
  ├─ 1. Load modules (constants, hooks, context, helpers, plugins, config, content, rendering)
  ├─ 2. createContext()
  │     ├─ Parse + merge config (default ← custom)
  │     ├─ loadGlobalPlugins() → fires Hook::CONTEXT_READY
  │     ├─ Determine contentDir (custom content or demo fallback)
  │     ├─ Parse REQUEST_URI → requestPath
  │     └─ Resolve template paths (custom fallback to default)
  │
  ├─ 3. Check custom/assets/{path} → serve static file + exit
  ├─ 4. Check content/{path} for static asset (css/img/pdf/font) → serve + exit
  │
  ├─ 5. Path ends with feed.xml? → Atom feed generation
  │    ├─ Strip feed.xml, resolve parent as list directory
  │    ├─ Check feed = true in metadata, otherwise 404
  │    ├─ buildListItems() + renderContentFile() for full content
  │    └─ Output Atom XML + exit
  │
  ├─ 6. Empty path? → frontpage: findAllContentFiles + renderMultipleFiles
  │
  └─ 7. parseRequestPath() → {type, path}
        │
        ├─ "page": trailing slash redirect → findAllContentFiles → renderMultipleFiles
        │    (fires Hook::PROCESS_CONTENT for file filtering)
        │    (fires Hook::TEMPLATE_VARS before template render)
        │    Template chain: content → page.php → base.php
        │
        ├─ "list": trailing slash redirect → buildListItems() from helpers.php
        │    ├─ Check hide_list metadata → treat as page if true
        │    ├─ Select list template from metadata page_template
        │    ├─ buildListItems(): metadata, titles, dates, covers for each subdir
        │    ├─ Sort items by date (metadata `order` = ascending|descending)
        │    ├─ Store pageTitle, metaDescription, feedUrl etc. on context
        │    ├─ Fire Hook::TEMPLATE_VARS
        │    └─ Template chain: items → list-*.php → base.php (via renderTemplate)
        │
        └─ "not_found": 404 response
```

## Module Dependency Order

Loaded sequentially in `router.php`:

```
constants.php → hooks.php → context.php → helpers.php → plugins.php → config.php → content.php → rendering.php
```

`config.php` calls `createContext()` which triggers plugin loading, so `hooks.php` and `plugins.php` must be loaded before it.

## Page vs List Detection

A resolved directory becomes a **list** if it contains subdirectories, otherwise a **page**. Override with `hide_list = true` in metadata to force page rendering on directories with children.

## Deployment Models

### Framework development (this repo)

Both `app/` and `custom/` live in the same repository. `custom/` holds demo/test overrides.

### Site development (separate repo)

The site is its own git repository containing `custom/`, content, and deployment config. `app/` is included as a symlink, git submodule, or copied directory pointing to a specific framework version. The site repo never modifies `app/`.

Typical site repo layout:

```
my-site/                    # Site git repo
  app/ → ../folderweb/app   # Symlink to framework (or submodule, or copy)
  custom/                   # Site-specific templates, styles, plugins, config
  content/                  # Website content (often the document root)
  devel/                    # Site's own dev environment config (optional)
```

Either direction works: `app/` symlinked into a site repo, or `custom/` symlinked into the framework repo during development.

## Demo Fallback

When `content/` (document root) has no files, `app/default/content/` is used automatically. This is **demo mode only** — production sites always provide their own content via the document root.