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. |
| `config.ini` | Plaintext INI | Legacy root-level configuration artifact; not loaded by the application bootstrap. |

## 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/OpenMind/Api/AdminController.php` |
| `AdminController::CONFIGURATION_BACKUP_FILE` | `cfg/config.bin.old` | `src/OpenMind/Api/AdminController.php` |
| `OMUtils::DEFAULT_SOCKET_TIMEOUT_SECONDS` | `5` | `src/OpenMind/System/OMUtils.php` |

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