> ## Documentation Index
> Fetch the complete documentation index at: https://api-documentation.kare-app.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Vue d'ensemble

> Topologie des environnements, des containers et du pipeline de livraison

## L'état réel aujourd'hui

<Warning>
  Un seul stage est vivant : **`staging`**. Les scripts partagés (`.github/scripts/_common.sh`)
  n'acceptent que `SUPPORTED_STAGES="staging"` et `infrastructure/` ne contient qu'une seule racine
  OpenTofu (`envs/staging`). Les workflows `release.yml` / `hotfix.yml` visent `prod` et définissent
  le contrat de livraison, mais **prod n'existe pas encore** : ils échoueront tant que le stage n'a
  pas été cloné (state, credentials, domaines, secrets).
</Warning>

| Stage     | Existe  | Base de données                  | Déclencheur                                |
| --------- | ------- | -------------------------------- | ------------------------------------------ |
| PR / CI   | oui     | Postgres éphémère dans le runner | chaque PR                                  |
| `staging` | oui     | Postgres Scaleway `staging`      | merge sur `main` (si le switch est activé) |
| `prod`    | **non** | —                                | `release.yml` / `hotfix.yml`, manuels      |

## Une image API, quatre audiences

```mermaid theme={null}
flowchart TD
    C["apps/api — un seul code"] -->|1 image Docker api| R
    C --> B
    C --> A
    C --> P
    R["kare-staging-api-rs<br/>APP_AUDIENCE=rs"]
    B["kare-staging-api-bo<br/>APP_AUDIENCE=bo"]
    A["kare-staging-api-ad<br/>APP_AUDIENCE=ad"]
    P["kare-staging-api-pr<br/>APP_AUDIENCE=pr"]
```

`APP_AUDIENCE` est lu au démarrage et **n'a aucune valeur par défaut** : absente ou inconnue, le
process crashe immédiatement. La variable est posée par OpenTofu sur chaque container, et par les
scripts `yarn dev:<audience>` en local.

## Les paires front / audience

Chaque front ne parle qu'à **son** audience. Un target `pair-*` déploie les deux ensemble.

| Audience | Container API         | Front             | Container front                 | Domaine staging          |
| -------- | --------------------- | ----------------- | ------------------------------- | ------------------------ |
| `rs`     | `kare-staging-api-rs` | `apps/kare`       | `kare-staging-front-kare`       | `rs.staging.kare-app.fr` |
| `bo`     | `kare-staging-api-bo` | `apps/backoffice` | `kare-staging-front-backoffice` | `bo.staging.kare-app.fr` |
| `ad`     | `kare-staging-api-ad` | `apps/audit`      | `kare-staging-front-audit`      | `ad.staging.kare-app.fr` |
| `pr`     | `kare-staging-api-pr` | `apps/provider`   | `kare-staging-front-provider`   | `pr.staging.kare-app.fr` |

API : `https://api.<audience>.staging.kare-app.fr`, sonde de santé `/health/ready`.
Fronts : sonde `/health`.

<Note>
  `pr`, `kare` et `provider` n'existent que sur staging. Le jour où prod est créée, le target `all`
  de prod exclura ces trois composants jusqu'à leur clonage.
</Note>

## Qui possède quoi

```mermaid theme={null}
flowchart LR
    T["OpenTofu"] -->|VPC, Postgres, Redis, buckets,<br/>registry, IAM, secrets, domaines, TLS| I["Infra + config des containers"]
    G["GitHub Actions"] -->|build, migrations, update image| M["Image des containers"]
```

La frontière est explicite : les ressources container OpenTofu portent
`lifecycle { ignore_changes = [image] }`. Un déploiement de code ne fait **jamais** de `tofu apply`,
et un `tofu apply` ne remet **jamais** une vieille image.

## Le pipeline unique

Tout déploiement avant (auto ou manuel) passe par `deploy-stack.yml` :

```mermaid theme={null}
flowchart LR
    P[parse target] --> Q[QA gate<br/>API + fronts]
    Q --> D[build image SHA7<br/>+ migrations<br/>+ update container]
    D --> H[health gate<br/>HTTP readiness]
    H --> L["promote<br/>staging-latest"]
    L --> V[verdict]
```

Points non négociables :

* les migrations Prisma tournent **avant** le flip d'image ;
* `staging-latest` ne bouge **qu'après** un health gate vert — c'est l'image que OpenTofu utilise à la
  création d'un container, donc elle doit toujours signifier « dernière image saine » ;
* **aucun rollback automatique** : la reprise est `rollback.yml`, manuel et explicite.

## Pour aller plus loin

<CardGroup cols={2}>
  <Card title="Dev local" href="/devops/local-dev">
    Compose, audiences, ports
  </Card>

  <Card title="CI sur les PR" href="/devops/ci">
    Les gates et le seul check bloquant
  </Card>

  <Card title="Déployer" href="/devops/deploy">
    Auto-staging, deploy manuel, rollback
  </Card>

  <Card title="Infrastructure" href="/devops/infrastructure">
    OpenTofu, plan revu, bootstrap
  </Card>
</CardGroup>