Raiju/README.md

# Raiju CMS ⚡️

<img src="raijulogo.png" alt="Raiju Logo" width="200" height="auto">

<img src="raiju-mascot.png" alt="Raiju Mascot" width="100" height="auto">

Lightning fast. Lightweight. Elusive.

A flat-file CMS built on PHP with no database. Content lives in JSON files, pages are PHP templates, and an inline editor lets you edit everything directly on the page. Zero dependencies, zero build steps.

**Current release:** 1.0.0, tracked in [`VERSION`](VERSION). Examples and full
documentation at [1studi.ru](https://1studi.ru/).

**Upgrading an existing site:** read the [upgrade guide](UPGRADING.md) before
replacing files. Custom save API integrations require resource revisions.
Release metadata and historical date notes are documented in [RELEASES.md](RELEASES.md).

## Features

- **No database** -- all content stored as JSON files
- **Inline editing** -- click and edit text, images, and links on the live page
- **Multi-language** -- built-in language switching and per-language content files
- **Block-based content** -- 11 block types (text, heading, quote, list, image, card, youtube, soundcloud, audio, divider, spacer)
- **Render components** -- pricing tables, FAQ accordions, team grids, feature grids, galleries, timelines, stats, testimonials, comparison tables, news listings, breadcrumbs
- **Dark/light theme** -- toggle with localStorage persistence
- **Accessibility foundations** -- skip links, landmarks, reduced-motion support, labelled controls, and SEO health checks for missing image alt text
- **Access controls** -- maintenance mode with preview bypass and password-protected private pages
- **Customizable lock/login screens** -- logo/favicon, image layouts, overlays, and login box colors
- **SEO/AEO tools** -- per-page metadata, Open Graph image fallback, sitemap/robots, and health indicators
- **AI tools** -- server-side AI gateway plus frontend editor Copilot for safe chat guidance, field suggestions, content drafts, image generation/editing, usage limits, audit logs, and provider-specific API keys
- **Custom layouts** -- full PHP template control with editable field API
- **JSON-backed forms** -- manage multiple simple forms from JSON, render them in templates, and collect submissions in the dashboard inbox
- **Automatic backups** -- per-page JSON history with restore via admin panel
- **Site backup & restore** -- download full site as ZIP, restore from backup
- **Scheduled backups** -- server-cron or web-cron full-site ZIP backups with retention and storage limits
- **Remote backup targets** -- upload scheduled ZIPs to Dropbox, Google Drive, OneDrive, SFTP/SCP, S3-compatible storage, or WebDAV
- **Forms & messages** -- lazy-loaded, spam-protected public forms with local message storage, optional SMTP, and form-based inbox filtering
- **News/blog system** -- post management with listing and single-post views
- **Event management** -- calendar events with multi-language support
- **No build step** -- plain PHP, HTML, CSS, vanilla JS

## Quick Start

```bash
# 1. Clone the repository
git clone http://192.168.0.47:3000/touche/raiju.git
cd raiju

# 2. Start the development server
php -S localhost:3000 router.php

# 3. Open the setup wizard
# Visit http://localhost:3000/admin/setup.php
# Set your site name, language, and admin password
```

For large image uploads raise the CLI limits (the default `upload_max_filesize` is often 2M):

```bash
php -d upload_max_filesize=20M -d post_max_size=25M -S localhost:3000 router.php
```

That's it. Your site is running.

Before uploading or upgrading a site, follow
[Routing and deployment verification](ROUTING.md). Local PHP routing and Apache
can differ, especially when clean URLs share names with physical directories.
After the first upload, open **System status** in the dashboard: its security
check confirms that internal folders such as `content/` and `backups/` cannot
be downloaded. An nginx proxy in front of Apache can bypass `.htaccess`; see
[Hosting proxies and internal folders](ROUTING.md#hosting-proxies-and-internal-folders).

## Built for AI

Raiju ships with structured documentation designed for AI coding agents:

- **`AI-AGENT-GUIDE.md`** -- tool-neutral agent guide with block types, template API, and step-by-step instructions for creating pages.
- **`AGENTS.md` / `CLAUDE.md`** -- short entry points for tools that auto-load those filenames; both point to the shared guide.
- **`SKILLS.md`** -- task-oriented workflows for common agent jobs.
- **`architecture.md`** -- full technical reference covering JSON schemas, every PHP function signature, API endpoints, and the inline editor system.

An AI agent can create a new page, build a custom layout, add content blocks, and style components without asking you how things work. The documentation gives it everything it needs.

## Requirements

- PHP 8.1 is the language minimum; use a [currently supported PHP branch](https://www.php.net/supported-versions.php) in production (8.4 or 8.5 recommended).
- CI tests PHP 8.1, 8.4 and 8.5. The PHP 8.1 check verifies compatibility;
  it does not extend PHP's upstream security support, which ended on 2025-12-31.
- PHP extensions: `mbstring`, `dom`, `fileinfo`, `session`; `zip` for backups, `curl` for provider integrations, and `gd` for image conversion.
- Apache with `mod_rewrite` (production) or PHP built-in server (development).
  If nginx serves static files in front of Apache (HestiaCP, or Plesk with
  "Serve static files directly by nginx"), block the internal folders in nginx
  too; see [ROUTING.md](ROUTING.md#hosting-proxies-and-internal-folders).
- No Composer, no npm, no database

## Directory Structure

```
admin/              Admin panel, API, setup wizard
api/                Public endpoints (contact form, etc.)
assets/
  images/           Uploaded images
  audio/            Uploaded audio files
  fonts/            Custom font files
cli/                Command-line tools (make.php, convert.php)
content/
  pages/            Page content JSON files
  forms/            Public form definitions
  news/             Blog post JSON files
  events.json       Events
  settings.json     Site-wide settings
  ai-settings.json  AI provider settings, feature flags, and limits (no keys)
  ai-secrets.json   AI API keys (provider, Brave, Pexels); never commit or serve
  ai-usage.json     AI usage counters
css/
  style.css         Core styles + CSS custom properties (do not edit)
  components.css    Core render component styles (do not edit)
  website.css       Site-owned overrides (created by you, optional)
includes/
  header.php        HTML head + navigation
  footer.php        Footer + scripts
  asset-helpers.php Core stylesheet loader (raijuCoreStyles)
  content-loader.php  Template API
  forms.php         JSON form loading, rendering, validation, notifications
  block-types.php   Block type definitions
  block-renderers/  Per-block-type renderers
  nav-config.php    Navigation configuration
  access-guard.php  Maintenance mode and private page enforcement
  ai/               AI provider gateway, Copilot context/actions, usage limits, audit, and generated images
  menu-helpers.php  Menu registry
  page.php          Front controller for JSON-only pages
js/                 Client-side scripts
examples/           Example templates, content, css/website.css.template
router.php          Development server router
```

## Creating a Page

### Option 1: JSON only (standard page)

Create `content/pages/en_about.json`:

```json
{
  "page": "en_about",
  "lang": "en",
  "title": "About Us",
  "description": "Learn more about us.",
  "sections": [
    { "id": "s1", "type": "heading", "text": "About Us", "level": "h1" },
    { "id": "s2", "type": "text", "title": "", "content": "<p>Our story.</p>" }
  ]
}
```

Nested clean URLs are supported as well. Use a slash in the public page path
and a reserved double underscore in the flat JSON filename:

```text
content/pages/en_products__vitamin-d.json  →  /products/vitamin-d
content/pages/de_produkte__vitamin-d.json  →  /de/produkte/vitamin-d
```

When the language is the configured default, its language prefix is omitted.
The Dashboard and `php cli/make.php --slug=products/vitamin-d --lang=en`
create this mapping automatically.

The page is now live at `/about`. No PHP file needed.

### Option 2: Custom layout (PHP template)

Create `en/services.php`:

```php
<?php
$pageTitle = 'Services';
$pageDescription = 'What we offer.';
$currentLang = 'en';
$currentPage = 'services';
$contentPage = 'en_services';
$basePath = '../';

include '../includes/header.php';
include '../includes/content-loader.php';
$_p = $contentPage;
?>
    <main class="main-content">
        <div class="content-inner">
            <h1><?php echo editableText($_p, 'hero.title', 'Our Services'); ?></h1>
            <?php echo renderFeatureGrid($_p); ?>
            <?php echo renderPricingTable($_p); ?>
        </div>
    </main>
<?php include '../includes/footer.php'; ?>
```

Create `content/pages/en_services.json` with the matching data structure.

See `examples/` for complete working examples.

## Accessibility Best Practices

Raiju provides a basic accessible foundation for public pages and admin tools: skip links, landmark-friendly templates, keyboard focus styles, reduced-motion handling, labelled controls, and SEO health checks for missing image alt text.

When building custom templates or site-specific components, follow these rules:

- Use one clear `<main>` area per page. Core templates expose `id="main-content"` for the skip link; custom templates should include the same id or let `includes/footer.php` add it to the first `<main>`.
- Keep heading order meaningful. Each public page should have one visible H1, then nested H2/H3 sections.
- Enter useful alt text for informative images. Leave alt empty only for purely decorative images.
- Use real buttons for actions and real links for navigation.
- Keep visible focus states intact; do not remove outlines without replacing them.
- Respect `prefers-reduced-motion` for page-specific animations.
- Label every form field and connect validation errors with nearby text.
- Test important pages with keyboard-only navigation and a screen reader before launch.

## Access Controls

Raiju includes frontend access controls without adding a database:

- **Maintenance mode** lives in **Dashboard -> Settings -> Access**. It can show a maintenance, back-soon, or launch-countdown page with custom title/text, optional unavailable-until time, and optional countdown.
- **Preview bypass** is configured with a URL parameter and secret key. Visiting a URL like `/?preview=secret-value` stores a session bypass so editors or clients can review the site while maintenance mode is active.
- **Private pages** are set per page in the Content Editor's **Access** card. Set visibility to `Private`, enter a password, and optionally customize the password page title/text.
- **Logged-in admins and editors bypass** maintenance mode and private page locks automatically.
- **Passwords and bypass secrets are hashed** in JSON. Do not store plaintext passwords directly in `content/pages/*.json` or `content/settings.json`.

## Theming

All design tokens are CSS custom properties defined in `css/style.css` (Raiju Core). To customize them for your site, **don't edit `style.css` directly** -- it gets overwritten on upgrades. Instead, copy the override template and edit your own file:

```bash
cp examples/css/website.css.template css/website.css
```

`includes/header.php` loads `css/website.css` automatically after Core, so any `:root` overrides you set there win:

```css
:root {
    --color-primary: #2563eb;
    --color-text: #171717;
    --font-display: system-ui, -apple-system, sans-serif;
    --spacing-md: 2rem;
}
```

Dark theme variables are included and toggled via `data-theme="dark"` on the `<html>` element.

To use custom fonts, place font files in `assets/fonts/` and define `@font-face` rules in `css/fonts.css`. `includes/header.php` loads `css/fonts.css` automatically when both the file and the `assets/fonts/` directory exist.

## License

This project is licensed under the Mozilla Public License 2.0. See
[LICENSE](LICENSE) for details.

Third-party components and their license terms are listed in
[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.