Merge pull request #172 from dotkernel/file-structure-accuracy

Correct v7 file structure page

Author: arhimede

docs/book/v7/introduction/file-structure.md

@@ -2,7 +2,7 @@
 
 ## Summary
 
-A tour of the directories a default Dotkernel API installation ships with — `bin` for CLI entry points, `config` and `config/autoload` for application and service configuration, `data` for caches, migrations and OAuth keys, `log` for daily logs, `public` as the web entry point, and `src` for the modules — plus the folders and files each module is expected to contain.
+A tour of the directories a default Dotkernel API installation ships with — `bin` for CLI entry points, `config` and `config/autoload` for application and service configuration, `data` for caches, lock files and OAuth keys, `log` for daily logs, `public` as the web entry point, and `src` for the modules — plus the folders and files each module is expected to contain.
 
 ## Details
 
@@ -13,29 +13,37 @@ When using Dotkernel API, the following structure is installed by default:
 
 ![Dotkernel API File Structure!](https://docs.dotkernel.org/img/api/v7/file-structure-dk-api.png)
 
-## Special purpose folders
+## Special purpose folders and files
 
 * `.github` - Contains GitHub workflow files
-* `.laminas-ci` - Contains laminas-ci workflow files
+* `.laminas-ci.json` - laminas-ci configuration; a single file, not a folder
+* `documentation` - Postman and Bruno collections for the shipped endpoints, plus notes on the CLI commands
 
 ## `bin` folder
 
 This folder contains:
 
-* `clear-config-cache.php` - Removes the config cache file `data/cache/config-cache.php`; available only when development mode is enabled
+* `clear-config-cache.php` - Removes the config cache file `data/cache/config-cache.php`; can also be invoked as `composer clear-config-cache`
 * `cli.php` - Used to build console applications based on [laminas-cli](https://github.com/laminas/laminas-cli)
-* `doctrine` - Used by the doctrine fixtures to populate the database tables
+* `composer-post-install-script.php` - Runs after `composer install` and copies the shipped distributable config files into place; it asks nothing and needs no input
+* `doctrine` - Doctrine ORM console, used by the fixtures commands to populate the database tables
+* `generate-oauth2-keys.php` - Generates the OAuth2 key pair and encryption key into `data/oauth`
 
 ## `config` folder
 
 This folder contains all application-related config files:
 
-* `cli-config.php` - Command line interface configuration used by migrations, fixtures, cron jobs
-* `config.php` - Registers ConfigProviders for installing packages
+* `cli-config.php` - Doctrine Migrations entry point; builds the `DependencyFactory` from the `doctrine.migrations` config
+* `config.php` - Registers ConfigProviders for installing packages, and sets the config cache path
 * `container.php` - Main service container that provides access to all registered services
 * `development.config.php.dist` - Activates debug mode; gets symlinked as `development.config.php` when enabling development mode
-* `migrations.php` - Configuration for database migration, like migration file location and table to save the migration log
 * `pipeline.php` - Contains a list of middlewares, in the order of their execution
+* `routes.php` - Application-wide route registration; ships empty, because each module declares its own routes in its `RoutesDelegator`
+
+### Note
+
+> There is no `config/migrations.php`.
+> Migration settings — the `doctrine_migration_versions` table and the `src/Core/src/App/src/Migration` path — are declared in `Core\App\ConfigProvider` and read through `config/cli-config.php`.
 
 ### `config/autoload` folder
 
@@ -46,29 +54,37 @@ This folder contains all service-related local and global config files:
 * `content-negotiation.global.php` - Configures request and response formats
 * `cors.local.php.dist` - Configures Cross-Origin Resource Sharing, like call origin, headers, cookies
 * `dependencies.global.php` - Sets global dependencies that should be accessible by all modules
-* `development.local.php.dist` - Gets symlinked as `development.local.php` when enabling development mode; activates error handlers
-* `doctrine.global.php` - Configuration used by Object–relational mapping
+* `development.local.php.dist` - Gets symlinked into place when enabling development mode; activates error handlers
 * `error-handling.global.php` - Configures and activates error logs
-* `local.php.dist` - Local configuration file where you can overwrite application name and URL
+* `local.php.dist` - Local configuration file: database credentials, application name and URL, OAuth2 key paths
 * `local.test.php.dist` - Local configuration for functional tests
-* `mail.local.php.dist` - Mail configuration; e.g. sendmail vs smtp, message configuration, mail logging
+* `mail.local.php.dist` - Mail configuration; e.g. sendmail vs smtp, message configuration, mail logging. Not committed: the post-install script copies it out of `dotkernel/dot-mail` during installation
 * `mezzio.global.php` - Mezzio core config file
-* `mezzio-tooling-factories.global.php`  Add or remove factory definitions
+* `problem-details.global.php` - Maps HTTP status codes to the `type` URI used in problem details responses
 * `response-header.global.php` - Defines headers per route
-* `templates.global.php` - `dotkernel/dot-twigrenderer` config file
+* `templates.global.php` - Configures `Api\App\Template\RendererInterface`, including the `phtml` template extension
+
+### Note
+
+> Doctrine is **not** configured from this folder.
+> There is no `doctrine.global.php`; ORM, migration and fixture settings come from the module `ConfigProvider`s, and connection credentials from the local config file.
 
 ## `data` folder
 
 This folder is a storage for project data files and service caches.
 It contains these folders:
 
-* `cache` - Cache for e.g. Twig files
-* `doctrine` - Database migrations and fixtures
+* `cache` - Holds `config-cache.php`, the merged configuration cache written when `ConfigAggregator::ENABLE_CACHE` is on
 * `oauth` - Encryption, private and public keys needed for authentication
 * `lock` - Contains lock files generated by [`dotkernel/dot-cli`](https://docs.dotkernel.org/dot-cli/v3/lock-files/)
 
 > AVOID storing sensitive data on the repository!
 
+### Note
+
+> There is no `data/doctrine`.
+> Migrations live in `src/Core/src/App/src/Migration` and fixtures in `src/Core/src/App/src/Fixture`, both inside the `Core` module.
+
 ## `log` folder
 
 This folder stores daily log files.
@@ -80,8 +96,10 @@ This folder contains all publicly available assets and serves as the entry point
 
 * `uploads` - Normally contains files uploaded via the application
 * `.htaccess` - Server configuration file used by Apache web server; it enables the URL rewrite functionality
+* `.well-known` - Contains `security.txt`, the [RFC 9116](https://www.rfc-editor.org/rfc/rfc9116) contact file for reporting vulnerabilities
+* `favicon.ico` - The site icon browsers request by default
 * `index.php` - The application's main entry point
-* `robots.txt.dist` - A sample robots.txt file that allows/denies bot access to certain areas of your application; activate it by duplicating the file as `robots.txt` and comment out the lines that don't match your environment
+* `robots.txt` - Allows or denies bot access to parts of your application; it is a live file, so edit it to match your environment
 
 ## `src` folder
 
@@ -95,6 +113,9 @@ These are the modules included by default:
 * `Security` - Contains security-related functionality
 * `User` - Contains functionality for managing regular users
 
+`Core` is itself split by domain under `src/Core/src`, into `Admin`, `App`, `Security`, `Setting` and `User`.
+See [Core and App](../extended-features/core-and-app.md).
+
 ### Module contents
 
 Each Module folder, in turn, should contain the following folders, unless they are empty:
@@ -116,9 +137,13 @@ The `src` folder in each Module folder normally also contains these files:
 ### `templates` folder in Modules
 
 This folder contains the template files, used, for example, to help render e-mail templates.
+Of the shipped modules only `User` has one, at `src/User/templates/user`.
+
+> Templates are rendered by `Api\App\Template\Renderer`, a lightweight renderer for files combining PHP and HTML.
+> All template files have the extension `.phtml`.
+> The extension is set in `config/autoload/templates.global.php` and Twig is not used anywhere in the application.
 
-> `twig` is used as Templating Engine.
-> All template files have the extension `.html.twig`
+See [Rendering and sending emails](../core-features/rendering-and-sending-emails.md).
 
 ## FAQ
 
@@ -155,17 +180,30 @@ Only the `public` folder is served directly; everything else is routed through i
 A: `config/pipeline.php`, which lists the middlewares in execution order.
 See [Middleware flow](../flow/middleware-flow.md).
 
+**Q: Why is `config/routes.php` empty?**
+
+A: Because routes are declared per module.
+Each module's `RoutesDelegator` is registered as a delegator on `Mezzio\Application` in its `ConfigProvider`, so `config/routes.php` is left as an empty callable for application-wide routes you may want to add.
+
 **Q: What is the difference between `config` and `config/autoload`?**
 
 A: `config` holds application-level wiring — the container, the pipeline, the config aggregator.
-`config/autoload` holds per-service configuration, split into `*.global.php` files that are committed and `*.local.php` files that are not.
+`config/autoload` holds per-service configuration, split into committed `*.global.php` files and uncommitted local ones shipped via their distributable equivalents.
+
+**Q: Where are the database migrations and fixtures?**
+
+A: In `src/Core/src/App/src/Migration` and `src/Core/src/App/src/Fixture`.
+Both paths are declared in `Core\App\ConfigProvider`, not in a file under `config`.
+See [Generate database migrations](../commands/generate-database-migrations.md).
 
 **Q: Where are the OAuth2 keys kept?**
 
 A: In `data/oauth`.
-They are generated during installation and must never be committed.
+They are generated by `bin/generate-oauth2-keys.php` during installation and must never be committed.
 See [OAuth2 security](../security/oauth2-security.md).
 
-**Q: Why is `robots.txt` shipped as `robots.txt.dist`?**
+**Q: Which templating engine is used?**
 
-A: So you can activate it deliberately: copy it to `robots.txt` and comment out the lines that do not match your environment.
+A: None of the usual ones.
+`Api\App\Template\Renderer` renders `.phtml` files directly; there is no Twig anywhere in the codebase.
+See [Rendering and sending emails](../core-features/rendering-and-sending-emails.md).