<!-- file: docs/guides/CONFIGURATION.md -->
<!-- version: 5 -->

# Guide de configuration

## Objectif

Ce guide décrit le chargement des documents de configuration après leur séparation. La référence d’API générale reste `ks-config/USAGE.md` et la configuration logging appartient à `ks-logging`.

## Fichiers actifs

- `config/app.config.json` : configuration générale chargée par défaut ;
- `config/logging.config.json` : configuration logging chargée par défaut ;
- `config/example.app.config.json` et `config/example.logging.config.json` : exemples minimaux conformes ;
- `config/schemas/app.config.schema.json` : schéma général ;
- `config/schemas/logging.config.schema.json` : schéma logging ;
- `.env`, ou le fichier sélectionné par `KS_ENV_FILE` : valeurs d’environnement non versionnées ;
- `.env.example` : noms de variables attendues sans secrets réels.

`KS_CONFIG_PATH` et `KS_LOGGING_CONFIG_PATH` permettent de remplacer indépendamment les deux chemins par défaut.

## Configuration générale

L’API recommandée reste `ks_config::read_config_json_file_with_environment`. Elle :

1. charge `.env`, ou le fichier sélectionné par `KS_ENV_FILE`, sans écraser les variables du processus ;
2. lit le JSON général ;
3. résout les placeholders `${KS_*}` / `${KB_*}` ;
4. valide `config/schemas/app.config.schema.json` ;
5. désérialise `AppConfig` et applique les invariants métier ;
6. laisse `active_profile` sélectionner le profil applicatif actif.

```rust
let config = match ks_config::read_config_json_file_with_environment(
    std::path::Path::new("config/app.config.json"),
    std::path::Path::new("."),
) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let profile = match ks_config::active_profile(&config) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};
```

Le profil général ne contient plus de bloc `logging`.

## Configuration logging

`ks_logging::read_logging_json_file_with_environment` charge séparément le document logging et `ks_logging::active_logging_profile` sélectionne son profil actif.

```rust
let logging = match ks_logging::read_logging_json_file_with_environment(
    std::path::Path::new("config/logging.config.json"),
    std::path::Path::new("."),
) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let logging_profile = match ks_logging::active_logging_profile(&logging) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};
```

Les deux `active_profile` sont indépendants. Il n’existe aucun fallback implicite du profil logging vers le nom du profil applicatif.

## Invariants

- aucun secret réel ne doit être ajouté aux fichiers versionnés ;
- les placeholders non résolus doivent rester détectables ;
- chaque schéma embarqué doit rester identique au fichier sous `config/schemas/` ;
- les profils applicatifs et logging sont validés indépendamment ;
- `ks-config` ne possède plus de types logging ;
- tant que `0.5.1-pre.006` n’a pas introduit les DTO sûrs, la configuration runtime résolue reste strictement backend et ne doit pas être exposée telle quelle.

## Diagnostic

Pour isoler une erreur :

1. vérifier le fichier d’environnement chargé ;
2. vérifier séparément les chemins app et logging ;
3. valider chaque document contre son schéma ;
4. vérifier son `active_profile` ;
5. vérifier ensuite les rôles HTTP/WebSocket, stockage ou routes logging concernés.

Ne jamais écrire dans les logs le JSON résolu complet s’il contient une valeur issue de `KS_SECRET_*` ou `KB_SECRET_*`.

## Références

- `ks-config/README.md` et `ks-config/USAGE.md` ;
- `ks-logging/README.md` et `ks-logging/USAGE.md` ;
- `config/README.md` ;
- `docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`.