# PHPEngine

## Project Overview
PHPEngine 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