PHEngine

Project Overview

PHEngine is a PHP/Fat-Free Framework application with a React administration UI. It exposes a same-origin JSON API for session authentication, navigation, notifications, encrypted configuration, and user administration.

Tech Stack

PHP 8.5+, Fat-Free Framework 3.9, MySQL via F3 DB\SQL, React 19, React Router 7, MUI 9, Tailwind CSS 4, and Vite 7.

Architecture

index.php boots F3, loads cfg/config.bin, then discovers PluginStrategy subclasses from src/. Core\Api\Api registers /api/v1 routes; React in ui/app consumes them through a same-origin client.

Commands

composer install · npm ci · npm run buildDev · npm run buildProd · npm run watch · npm pack. Copy cfg/config.ini.example to the ignored cfg/config.ini and provision cfg/config.bin outside the repository. No test, lint, deploy, or configuration-generation command is declared.

Code Style

Use PSR-4 namespaces under Core\ and Modules\; match nearby PHP style and declare(strict_types=1) in modern API code. Preserve frontend import/component conventions; .prettierrc defines single quotes, semicolons, LF endings, and 200-column print width.

Coding Rules

A plugin directory is discovered only when it contains a same-named PHP initializer extending PluginStrategy.
Register API routes only in src/Core/Api/Api.php; controllers must return JSON through Controller helpers.
Protect authenticated state changes with the session CSRF token; enforce authorization server-side, not only in React routes.
Keep the username|password input to password hashing; a username change requires a new password.
Preserve the final-admin and self-deletion invariants in user management.
Treat cfg/config.bin and its plaintext source as sensitive configuration; preserve backup/restore behavior on writes.
Keep generated assets/app/ aligned with the Vite build; do not manually edit its hashed assets.

Design System

React pages use MUI components plus Tailwind utility classes. theme.js defines the palette, navigation colors, typography, and radius; AppShell renders the responsive dark navigation drawer with route-aware selection.

Constraints / What to Avoid

Do not bypass F3 session/CSRF checks, expose password hashes or configuration values, relax database uniqueness/locking safeguards, or add a frontend route without matching authorized navigation/API behavior.

Workflow

Inspect the applicable spec before changing Tier 1 modules. Make the smallest compatible change, then review route, authorization, configuration, and generated-asset implications. No automated test suite is configured.

When you modify code, update the relevant file in specs/.

References

@specs/file-structure.md — repository map and boot flow
@specs/commands.md — setup, build, package, and database commands
@specs/conventions-backend.md — PHP/F3 conventions
@specs/conventions-frontend.md — React/MUI conventions
@specs/conventions-database.md — MySQL schema and persistence rules
@specs/api-routes.md — JSON API contract
@specs/module-index.md — module priority map
@specs/identity/spec.md — authentication and user-management contracts
@specs/configuration/spec.md — configuration storage contract
@specs/integrations/index.md — external boundaries
@specs/rules/add-api-endpoint.md — API change recipe
@specs/rules/add-plugin.md — plugin change recipe

AGENTS.md 3.4 KB History Raw