Read this when changing runtime configuration loading, configuration administration, or config-file generation.

# Configuration

## Purpose
The application loads F3 globals from a runtime configuration file and provides an administrator-only API to read and replace its encoded content with a one-file backup.

## Data Model

| Artifact | Format | Role |
|---|---|---|
| `cfg/config.ini.example` | Plaintext F3 INI | Tracked template containing placeholders for deployment-specific values. |
| `cfg/config.ini` | Plaintext F3 INI | Ignored local configuration copied from the template; it may contain credentials. |
| `cfg/config.bin` | `base64(gzcompress(ini-text))` | Runtime configuration loaded by `index.php`. |
| `cfg/config.bin.old` | Previous `config.bin` bytes | Single backup created before an administrator save. |

## Runtime Globals

| Globals | Purpose |
|---|---|
| `AUTOLOAD`, `CACHE`, `UI`, `DEBUG`, `ENCODING`, `HIGHLIGHT`, `JAR.expire` | Fat-Free Framework runtime settings. |
| `DSN`, `dbuser`, `dbpass` | MySQL connection settings consumed by `Core\System\System`. |

## Business Rules
- Startup must validate PHP 8.5+, require `cfg/config.bin`, decode it to a temporary file, apply F3 configuration, then remove the temporary file.
- `Encrypt()`/`Decrypt()` provide reversible base64+gzip encoding, not secrecy. Treat every configuration artifact as sensitive because it can contain credentials.
- Operators copy `cfg/config.ini.example` to the ignored `cfg/config.ini` and provision `cfg/config.bin` outside the repository; no generation script is tracked.
- Only an authenticated `admin` may read decoded configuration or save a replacement; save also requires CSRF validation.
- Save first renames `config.bin` to `config.bin.old`, writes encoded replacement content, and restores the backup if writing the new file fails.
- The API accepts arbitrary string text; therefore callers must preserve valid F3 INI syntax and required runtime globals. No schema validation exists in the application.

## Constants

| Constant | Value | Location |
|---|---|---|
| `AdminController::CONFIGURATION_FILE` | `cfg/config.bin` | `src/Core/Api/AdminController.php` |
| `AdminController::CONFIGURATION_BACKUP_FILE` | `cfg/config.bin.old` | `src/Core/Api/AdminController.php` |
| `RuntimeServices::DEFAULT_SOCKET_TIMEOUT_SECONDS` | `5` | `src/Core/System/RuntimeServices.php` |

## Cross-links
See [API routes](../api-routes.md), [encrypted configuration integration](../integrations/encrypted-config.md), and [commands](../commands.md).