# Vue d'ensemble du schéma

Le schéma d'application Sovrium est un objet de configuration déclaratif comportant 19 propriétés racines. Seule `name` est obligatoire ; tout le reste est optionnel. Votre application peut ainsi évoluer par étapes — d'un simple identifiant jusqu'à une application full-stack — sans réécrire l'existant.

## Structure du schéma

```yaml
name: my-app # App identifier (required)
version: 1.0.0 # SemVer version
description: My application # One-line description
badge: false # "Built with Sovrium" badge (shown by default)

tables: [...] # Data models with 49 field types
pages: [...] # Server-rendered pages (~80 component types)
forms: [...] # Standalone forms capturing submissions
auth: { ... } # Authentication, roles, RBAC, 2FA
theme: { ... } # Design tokens (colors, fonts, etc.)
languages: { ... } # Multi-language support ($t: syntax)

automations: [...] # Event-driven workflows (triggers + actions)
actions: [...] # Reusable action templates ($ref)
connections: [...] # External-service credentials
agents: [...] # AI agents acting under an auth role
buckets: [...] # Named file-storage containers

components: [...] # Reusable UI templates ($ref, $variable)
analytics: { ... } # Cookie-free, first-party analytics
env: { ... } # Declared automation env vars ($env.NAME)
scripts: { ... } # Global page scripts
```

:::callout
**Complexité progressive.** Seule `name` est obligatoire. Ajoutez `tables`, `theme`, `pages`, `auth` et les autres sections à mesure que votre application évolue.
:::

## Propriétés racines

Le schéma d'application comporte 19 propriétés racines. Seule `name` est obligatoire.

| Propriété     | Type              | Description                                                                                                                                           |
| ------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string (requis)   | Identifiant d'application suivant les conventions de nommage npm. Minuscules, max 214 caractères, prend en charge le format à portée (`@scope/name`). |
| `version`     | string            | Chaîne Semantic Versioning 2.0.0 (par ex. `1.0.0`, `2.0.0-beta.1`). Alimente le registre de versions immuable.                                        |
| `description` | string            | Description de l'application sur une seule ligne (max 2000 caractères). Pas de sauts de ligne. Unicode et emojis pris en charge.                      |
| `badge`       | boolean           | Badge « Construit avec Sovrium » sur toutes les pages. Affiché par défaut ; `badge: false` le supprime — gratuit, une ligne, pour toujours.           |
| `tables`      | array             | Modèles de données avec 49 types de champ, relations, index, permissions et vues.                                                                     |
| `theme`       | object            | Jetons de design : couleurs, polices, espacements, ombres, animations, points de rupture et rayons de bordure.                                        |
| `languages`   | object            | Prise en charge multilingue avec la syntaxe de traduction `$t:`, détection du navigateur et routage par URL.                                          |
| `auth`        | object            | Stratégies d'authentification (email/mot de passe, lien magique, OAuth), rôles, RBAC, sessions et double authentification.                            |
| `analytics`   | object \| boolean | Analyses respectueuses de la vie privée, sans cookies, first-party. Définissez `true` pour les valeurs par défaut ou configurez avec des options.     |
| `components`  | array             | Modèles d'interface réutilisables avec référencement `$ref` et substitution `$variable`.                                                              |
| `pages`       | array             | Pages rendues côté serveur avec ~80 types de composants, métadonnées SEO et prise en charge i18n.                                                     |
| `forms`       | array             | Formulaires autonomes qui capturent des soumissions dans une table ou déclenchent une automatisation.                                                 |
| `connections` | array             | Identifiants réutilisables pour services externes : OAuth2, clé API, authentification basique et jeton bearer.                                        |
| `env`         | object            | Variables d'environnement déclarées résolues à l'exécution, référencées dans les actions comme `$env.NAME` (jamais journalisées).                     |
| `actions`     | array             | Modèles d'action réutilisables référencés depuis les automatisations via `$ref` avec `$vars`.                                                         |
| `automations` | array             | Workflows pilotés par événements : un déclencheur se déclenche, une séquence d'actions s'exécute.                                                     |
| `agents`      | array             | Agents IA agissant au nom d'un rôle d'authentification au sein d'un ensemble d'outils contraint, avec portes d'approbation et limites de débit.       |
| `buckets`     | array             | Conteneurs de stockage nommés avec des limites de fichiers et des permissions d'accès par bucket.                                                     |
| `scripts`     | object            | Scripts globaux chargés sur chaque page avant les scripts au niveau de la page.                                                                       |

## Détails des propriétés

Les règles et contraintes détaillées des propriétés racines scalaires — `name`, `version`, `description` et `badge` — sont présentées sur la page [Métadonnées de l'application](/fr/docs/app-metadata), qui documente également le registre de versions, la détection de dérive et l'obsolescence des brouillons.

### `name`

Le nom de l'application suit les conventions de nommage npm. En minuscules, compatible avec les URL et unique au sein de votre déploiement.

| Contrainte   | Description                                                                                                              |
| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
| Motif        | `^(?:@[a-z0-9-~][a-z0-9-._~]*/)?[a-z0-9-~][a-z0-9-._~]*$`. Lettres minuscules, chiffres, traits d'union, points, tildes. |
| Longueur max | 214 caractères maximum (préfixe `@scope/` inclus s'il y a une portée).                                                   |
| Avec portée  | Prend en charge les paquets à portée de style npm : `@scope/name` (par ex. `@acme/dashboard`).                           |

```yaml
# Valid names
name: my-app
name: task-tracker-v2
name: '@acme/dashboard'
```

### `version`

Suit Semantic Versioning 2.0.0 ([semver.org](https://semver.org)). Format : `MAJOR.MINOR.PATCH` avec métadonnées de pré-version et de build optionnelles.

```yaml
version: 1.0.0 # Stable release
version: 2.0.0-beta.1 # Pre-release
version: 1.0.0+build.42 # Build metadata
```

### `description`

Un texte sur une seule ligne décrivant l'application. Affiché dans l'interface d'administration et les métadonnées.

| Contrainte   | Description                                                                      |
| ------------ | -------------------------------------------------------------------------------- |
| Format       | Une seule ligne. Aucun saut de ligne (`\n`) autorisé.                            |
| Longueur max | 2000 caractères maximum.                                                         |
| Unicode      | Prise en charge complète d'Unicode, y compris les emojis et caractères spéciaux. |

## Formats de configuration

Sovrium accepte la configuration en YAML, JSON et TypeScript. Le YAML est recommandé pour sa lisibilité ; le JSON convient à la génération programmatique ; le TypeScript ajoute la sécurité de typage via `@sovrium/types`. Les configurations volumineuses peuvent être réparties sur plusieurs fichiers avec `$ref`. Consultez [Fichiers de configuration](/fr/docs/configuration-files) pour le guide complet.

```yaml
# YAML format (recommended)
name: my-app
version: 1.0.0
tables:
  - id: 1
    name: tasks
    fields:
      - { id: 1, name: title, type: single-line-text }
```

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "tables": [
    {
      "id": 1,
      "name": "tasks",
      "fields": [{ "id": 1, "name": "title", "type": "single-line-text" }]
    }
  ]
}
```

## Validation inter-sections

Les sections racines sont validées _ensemble_, et non isolément. Sovrium rejette une configuration avant le démarrage du serveur lorsque, par exemple :

- un champ `user`/`created-by`/`updated-by` existe mais `auth` n'est pas configuré ;
- une permission de table ou de bucket nomme un rôle qui n'est pas déclaré ;
- un champ de pièce jointe référence un `bucket` absent de `buckets` ;
- un déclencheur ou une action d'automatisation d'enregistrement référence une table qui n'existe pas ;
- une action `$ref` d'automatisation, une référence d'agent IA ou un déclencheur de formulaire nomme quelque chose de non déclaré.

Exécutez [`sovrium validate`](/fr/docs/cli) pour vérifier ces règles avant le déploiement.

## Pages associées

- [Métadonnées de l'application](/fr/docs/app-metadata) — `name`, `version`, `description`, `badge`, registre de versions, détection de dérive.
- [Vue d'ensemble des tables](/fr/docs/tables-overview) — modèles de données et 49 types de champ.
- [Vue d'ensemble des pages](/fr/docs/pages-overview) — ~80 types de composants pour les pages rendues côté serveur.
- [Vue d'ensemble des formulaires](/fr/docs/forms-overview) — formulaires autonomes et soumissions.
- [Vue d'ensemble de l'authentification](/fr/docs/auth-overview) — stratégies, rôles et RBAC.
- [Vue d'ensemble des automatisations](/fr/docs/automations-overview) — déclencheurs, actions et connexions.
- [Vue d'ensemble de l'IA](/fr/docs/ai-overview) — agents et champs IA-natifs.
- [Vue d'ensemble des buckets](/fr/docs/buckets-overview) — conteneurs de stockage de fichiers.
- [Vue d'ensemble des enregistrements](/fr/docs/records-overview) — interrogation et modification des lignes à l'exécution.
- [Thème](/fr/docs/theme) · [Design responsive](/fr/docs/responsive-design) · [Animations](/fr/docs/animations) · [Langues](/fr/docs/languages).