> ## 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.

# Dev local

> Services de support en Docker, applications sur la machine hôte

## Le modèle

```mermaid theme={null}
flowchart LR
    subgraph D["docker compose (apps/api)"]
      PG[postgres]
      RD[redis]
      GA["garage (S3)"]
      MP["mailpit (mail)"]
      OB["loki + alloy + grafana"]
      TR["traefik (*.kare.localhost)"]
    end
    H["Ta machine : API + fronts en hot-reload"] --> D
```

Docker ne fait tourner que les **dépendances**. L'API et les fronts tournent sur l'hôte, en
hot-reload. Un profil `container` existe pour tester l'image de l'API, ce n'est pas le mode par défaut.

## Démarrer

<Steps>
  <Step title="Services de support">
    ```bash theme={null}
    cd apps/api
    make up          # = yarn dev:up (compose up -d)
    ```
  </Step>

  <Step title="Base de données">
    ```bash theme={null}
    yarn workspace @kare/database migrate:dev
    ```
  </Step>

  <Step title="API, une audience par terminal">
    ```bash theme={null}
    make dev-rs   # ou dev-bo / dev-ad / dev-pr
    ```
  </Step>

  <Step title="Un jeu de données">
    Voir [Seed local](/onboarding/seed/local).
  </Step>
</Steps>

`make help` liste toutes les cibles. Le Makefile **délègue** à yarn : les scripts `package.json`
restent la source de vérité (turbo + CI n'appellent jamais le Makefile).

## Ports

| Service               | Port                                             | URL                             |
| --------------------- | ------------------------------------------------ | ------------------------------- |
| API                   | `3000` (`PORT` dans `.env`)                      | `http://localhost:3000`         |
| Front `kare`          | `3000` en `dev`, `3000` en `start`               | —                               |
| Front `backoffice`    | `3000` en `dev` (défaut Next), `3001` en `start` | —                               |
| Front `audit`         | `3000` en `dev` (défaut Next), `3002` en `start` | —                               |
| Front `provider`      | `3003` en `dev` et en `start`                    | —                               |
| Postgres              | `5434`                                           | —                               |
| Redis                 | `6381`                                           | —                               |
| Garage (S3)           | `3900`                                           | `http://garage.kare.localhost`  |
| Mailpit (SMTP `1025`) | —                                                | `http://mail.kare.localhost`    |
| Grafana               | —                                                | `http://grafana.kare.localhost` |
| Traefik               | `80`                                             | `http://traefik.kare.localhost` |
| Loki                  | `3100`                                           | —                               |

<Warning>
  Seul `provider` épingle son port en `dev` ; `kare`, `backoffice` et `audit` utilisent le défaut Next
  (`3000`, auto-incrémenté s'il est pris) et n'écoutent sur `3001` / `3002` qu'en `yarn start`. L'API
  écoute aussi `3000` : pour lancer les deux, change `PORT` dans `apps/api/.env` ou passe
  `PORT=` devant `make dev-rs`, et ajuste le `NEXT_PUBLIC_API_URL` du front.
</Warning>

<Note>
  `http://api.kare.localhost` ne route que le service `api` de compose, donc uniquement en
  `--profile container`. En mode par défaut (API sur l'hôte), on tape `http://localhost:3000`.
</Note>

## Commandes utiles

| Commande                          | Effet                                                       |
| --------------------------------- | ----------------------------------------------------------- |
| `make up` / `make down`           | démarre / arrête la stack de support                        |
| `make db`                         | Postgres seul                                               |
| `yarn dev:reset`                  | détruit les volumes et repart de zéro                       |
| `yarn dev:logs` / `yarn dev:urls` | logs agrégés / rappel des URLs                              |
| `make test`                       | suite complète (unit + intégration, exige Postgres + Redis) |
| `make test-unit`                  | unitaires seuls, aucune dépendance                          |
| `make qa`                         | lint + typecheck + tests                                    |
| `make openapi`                    | régénère `openapi/<audience>/openapi.json`                  |

## Mails et fichiers

* Tout mail sortant part vers **Mailpit** : les OTP de connexion prestataire se lisent dans son interface.
* Les uploads vont dans **Garage**, compatible S3, initialisé par le service `garage-init`.
* Les logs applicatifs passent par **Alloy → Loki → Grafana**, comme en staging.

## Fronts

```bash theme={null}
yarn workspace @kare/kare dev
yarn workspace @kare/backoffice dev
```

`apps/kare` et `apps/provider` téléchargent le dist HeroUI Pro sous licence via
`scripts/pull-heroui-pro.mjs` : il faut un `HEROUI_AUTH_TOKEN` dans l'environnement, sinon le
`dev`, le `build` et le `typecheck` échouent.