ruben/folderweb
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Activity Actions

Update AGENT.md and add architecture documentation

Browse source 
Update AGENT.md to reflect current project structure and philosophy

Add comprehensive architecture documentation covering:
- Directory layout
- Stable contracts
- Request flow
- Module dependencies
- Page vs list detection
- Deployment models
- Demo fallback

Remove outdated plugin system documentation
Add new content system documentation
Add configuration documentation
Add context API documentation
Add hooks and plugins documentation
Add templates documentation
Add rendering documentation
Add development environment documentation
This commit is contained in:
Ruben 2026-02-05 23:30:44 +01:00
parent 696b0ad801
commit b03511f99b
11 changed files with 999 additions and 1381 deletions
Download patch file Download diff file Expand all files Collapse all files

47
AGENT.md
View file

@ -1,22 +1,41 @@
# FolderWeb
Minimal file-based CMS. Folders = URLs. PHP 8.4+, no JS, no frameworks, no build tools.
## Philosophy
Minimal PHP for modern conveniences. Prioritize longevity (decade-scale maintainability) by avoiding volatile dependencies. Strictly add only what's essential—readable, simple, and future-proof.
Decade-scale maintainability. Only essential tech. Readable, simple, future-proof. No volatile dependencies.
## Two Modes of Work
1. **Building on top** (`custom/`): Create sites using the framework. Never modify `app/`. In this mode, `app/` is typically symlinked or submoduled from the framework repo into a separate site repo.
2. **Framework development** (`app/`): Evolve the core. Preserve all stable contracts (see architecture doc). `custom/` may be symlinked in from a site repo for testing.
## Core Constraints
**Minimalism:** Only essential tech (HTML, PHP 8.4+, CSS). No JS, frameworks, build tools, or package managers. Comments only for major sections.
**Frontend:**
- Classless, semantic HTML5
- Modern CSS: nesting, `oklch()`, grid, `clamp()`, logical props
- Responsive via fluid typography + flexible layouts
**Security:**
- Path validation blocks traversal
- Files restricted to document root
- Strict MIME types + no direct user-input execution
- **Stack:** HTML5, PHP 8.4+, CSS. Nothing else.
- **Frontend:** Classless semantic HTML, modern CSS (nesting, `oklch()`, grid, `clamp()`, logical props)
- **Security:** Path traversal protection, document root restriction, strict MIME types, escape all UGC
## Code Style
**PHP:** Modern syntax (arrow functions, null coalescing, match). Type hints where practical. Ternary for simple conditionals. Single-purpose functions.
**CSS:** Variables, native nesting, grid layouts. `clamp()` over `@media`. Relative units > pixels.
- **PHP:** Arrow functions, null coalescing, match expressions. Type hints where practical. Single-purpose functions. Comments only for major sections.
- **CSS:** Variables, native nesting, grid. `clamp()` over `@media`. Relative units.
- **Templates:** `<?= htmlspecialchars($var) ?>` for UGC. `<?= $content ?>` for pre-rendered HTML.
**Templates:** Escape output (`htmlspecialchars()` for UGC). Short echo tags (`<?= $var ?>`).
## Knowledge Base
Read these docs on-demand when working on related areas. Do not load all at once.
| Skill | File | Read When |
|---|---|---|
| Architecture | `docs/04-development/01-architecture.md` | Understanding project structure, request flow, module dependencies, stable contracts |
| Content System | `docs/04-development/02-content-system.md` | Working with routing, URL resolution, metadata, content discovery, navigation |
| Configuration | `docs/04-development/03-configuration.md` | Config loading, the `custom/` override system, static asset routing |
| Context API | `docs/04-development/04-context-api.md` | The Context class, Templates class, built-in context keys |
| Hooks & Plugins | `docs/04-development/05-hooks-plugins.md` | Hook system, plugin manager, writing plugins, the language plugin |
| Templates | `docs/04-development/06-templates.md` | Template hierarchy, resolution, variables, list item schema, partials |
| Rendering | `docs/04-development/07-rendering.md` | Rendering pipeline, Markdown caching, static file serving, Parsedown |
| Dev Environment | `docs/04-development/08-dev-environment.md` | Container setup, Apache config, performance profiling, test data generation |
Human-facing docs (tutorials, reference) are in `docs/01-getting-started/`, `docs/02-tutorial/`, `docs/03-reference/`.