phpengine/specs/file-structure.md

Read this when you need the repository map, boot order, or generated-file boundaries.

File Structure

Path	Purpose
index.php	HTTP/CLI bootstrap: Composer autoload, F3 singleton, encrypted runtime config, plugin composition, then run().
composer.json	PHP 8.5 and Fat-Free Framework dependencies; PSR-4 maps Core\ and Modules\.
cfg/config.ini.example	Tracked F3 configuration template with deployment placeholders.
cfg/config.ini	Ignored local F3 configuration, which may contain credentials.
cfg/config.bin	Runtime configuration consumed by index.php; provisioned outside the repository and not tracked.
scripts/	No tracked scripts.
src/Core/System/	Bootstrap, plugin discovery, framework services, role/user/inventory mappers, notifications, and error handling.
src/Core/Api/	API route registry and JSON controllers, including role and inventory administration.
src/Core/Admin/	Administration plugin that publishes the ID-1 administration menu hierarchy.
src/Modules/Blank/	Retained plugin directory that publishes the ID-2 Inventory Monitor menu entry.
ui/app/	Vite React source application.
ui/app/src/api/client.js	Same-origin API client and in-memory CSRF token holder.
ui/app/src/features/	Authentication, shell, administration, inventory demo, notification, and home UI features.
assets/app/	Ignored local Vite build output, including hashed JS/CSS and the manifest; do not edit manually.
assets/images/	Static images referenced by the React UI and runtime configuration.
vite.config.js	Builds ui/app into assets/app with base /phengine/assets/app/ and suppresses Rollup "use client" module-directive warnings.
phpengine.sql	MySQL schema and sample data dump, including the role catalog and inventory tables.

Boot and Request Flow

1. index.php validates PHP, decrypts cfg/config.bin, and invokes ApplicationComposition over src/.
2. Composition boots System first, then each discovered same-name directory initializer that extends PluginStrategy.
3. System configures F3 errors, cache, and the DB connection; Api registers JSON routes.
4. Vite-built React assets load under the configured base path and call /api/v1 through ui/app/src/api/client.js.

See module-index.md, api-routes.md, and rules/add-plugin.md.