# Circuy

Plateforme d'adoption numérique : un SDK exécute des parcours de guidage sur le site du client, une extension les crée sans code, un backend les stocke et les distribue.

Le contrat JSON de parcours est le pivot. Les paquets ne servent qu'à le produire, le distribuer ou l'exécuter.

## Monorepo

```
apps/api              Backend Hono + PostgreSQL (sert aussi le dashboard)
apps/dashboard        Application Vite + React + Tailwind
apps/extension        Extension Chrome d'édition (WXT)
packages/contracts    Schémas Zod et types du contrat JSON
packages/sdk          Moteur d'exécution et de rendu
docs/                 Intégration, conditions de publication, DPA et exploitation
```

Cahier des charges : [specifications/technical](specifications/technical).

## Prérequis

Node.js 22 (fichier `.nvmrc`) :

```bash
nvm install
nvm use
```

Sans nvm : installe la version 22 depuis https://nodejs.org.

pnpm (Corepack, livré avec Node) :

```bash
corepack enable
```

Docker, pour PostgreSQL local : https://docs.docker.com/get-docker/

Sur un serveur distant :

```bash
curl -fsSL https://get.docker.com | sh
```

Chromium Playwright, une fois, pour les e2e :

```bash
pnpm --filter @circuy/sdk exec playwright install chromium
```

## Commandes

### Première mise en route

```bash
pnpm install              # télécharge les dépendances de tous les paquets
docker compose up -d      # démarre PostgreSQL ; sans lui, API et tests d'intégration échouent
cp .env.example .env      # fournit DATABASE_URL et ALLOW_DEV_AUTH à l'API locale
pnpm db:migrate           # applique le schéma ; une base vide ne sert à rien avant ça
```

`ALLOW_DEV_AUTH=1` (dans `.env`) active `POST /v1/auth/dev`. C'est le raccourci de connexion locale ; il est refusé en production.

### Vérifier que le dépôt tient

```bash
pnpm check                # format, lint et imports SDK ; à lancer avant de committer
pnpm typecheck            # le compilateur TypeScript, pas l'exécution
pnpm test                 # tests unitaires et d'intégration (besoin de PostgreSQL)
pnpm db:restore-drill     # prouve qu'une sauvegarde se restaure, sur une base temporaire
```

`db:restore-drill` n'est pas un prérequis quotidien. C'est l'essai de restauration (une sauvegarde jamais restaurée n'en est pas une). Il ne touche pas à la base de travail.

### SDK

Le moteur s'éprouve sans backend, à partir de fichiers JSON locaux.

```bash
pnpm build:sdk                      # produit le fichier que le site client chargera
pnpm --filter @circuy/sdk demo      # page de démonstration : http://127.0.0.1:4173
pnpm test:e2e                       # un parcours réel dans Chromium, clavier et focus compris
```

### API

```bash
pnpm --filter @circuy/api dev       # backend local : http://localhost:8787
```

À lancer dès qu'on publie un parcours, qu'on ouvre le dashboard ou qu'on connecte l'extension. En production, Hono sert aussi les fichiers du dashboard.

### Extension

L'extension parle à l'API : les deux processus doivent tourner.

```bash
pnpm --filter @circuy/api dev
pnpm --filter @circuy/extension dev     # charge l'extension dans un Chrome de développement
pnpm test:e2e:extension                 # capture, édition et publication sans écrire de code
```

### Dashboard

Même dépendance à l'API. En local, Vite proxyfie `/v1` vers le backend.

```bash
pnpm --filter @circuy/api dev
pnpm --filter @circuy/dashboard dev     # tour de contrôle : http://127.0.0.1:5173
pnpm test:e2e:dashboard                 # tunnel de complétion après une exécution réelle du SDK
```

## Lots

| Lot | État |
| --- | --- |
| 0 — Socle | Fait |
| 1 — SDK | Fait |
| 2 — Backend | Fait |
| 3 — Extension | Fait |
| 4 — Mesure | Fait |
| 5 — Durcissement | Fait |