docs: ajout documentation de référence

README.md

@@ -1,2 +1,92 @@
 # expria-frontend
 
+Interface utilisateur d'Expria — Coach IA de préparation au TCF Canada.
+Plateforme SaaS francophone ciblant les candidats à l'immigration Express Entry
+(Algérie, Maroc, Cameroun).
+
+## Stack technique
+
+- **React 18** + **Vite** — frontend pur, pas de logique serveur
+- **TypeScript** — typage strict
+- **Tailwind CSS** — styles utilitaires
+- **Supabase JS** — authentification côté client uniquement
+
+## Documents de référence
+
+Lire ces fichiers avant toute modification :
+
+| Fichier | Contenu |
+|---|---|
+| `docs/DEVELOPMENT_PRINCIPLES.md` | Cycle de travail, règles, conventions — **obligatoire** |
+| `docs/ARCHITECTURE.md` | Stack, structure, flux de données |
+| `docs/PLANS_TARIFAIRES.md` | Plans Free / Standard / Premium et permissions |
+| `docs/PARCOURS_UTILISATEURS.md` | Parcours exact de chaque type d'utilisateur |
+| `docs/GOLDEN_DATASET.md` | Tests manuels anti-régression |
+
+## Structure des dossiers
+
+```
+src/
+├── api/              # Fonctions d'appel API (une par domaine)
+├── components/       # Composants React réutilisables
+│   ├── ui/           # Composants génériques (Button, Modal, Badge)
+│   ├── simulation/   # Composants spécifiques aux simulations
+│   ├── rapport/      # Composants d'affichage des rapports
+│   ├── dashboard/    # Composants du dashboard utilisateur
+│   └── paywall/      # Composants de blocage / upgrade
+├── pages/            # Pages de l'application (une par route)
+├── hooks/            # Hooks React personnalisés
+├── lib/
+│   ├── access.ts     # Source de vérité des permissions par plan ⚠️
+│   ├── supabase.ts   # Client Supabase (auth uniquement)
+│   └── constants.ts  # Constantes globales
+└── types/            # Types TypeScript partagés
+```
+
+> ⚠️ `src/lib/access.ts` est la source de vérité unique des permissions par plan.
+> Ce fichier doit rester identique à `src/lib/access.ts` dans `expria-backend`.
+> Toute modification des plans tarifaires met ce fichier à jour en premier.
+
+## Variables d'environnement
+
+Créer un fichier `.env` à la racine (ne jamais committer) :
+
+```
+VITE_API_URL=http://localhost:3000          # URL backend en développement
+VITE_SUPABASE_URL=https://xxx.supabase.co
+VITE_SUPABASE_ANON_KEY=xxx                  # Clé publique uniquement
+```
+
+> ❌ Aucune clé privée ne doit apparaître dans ce fichier ou dans le code frontend.
+
+## Commandes
+
+```bash
+# Installer les dépendances
+npm install
+
+# Démarrer en développement
+npm run dev
+
+# Builder pour la production
+npm run build
+
+# Prévisualiser le build
+npm run preview
+```
+
+## Déploiement
+
+Plateforme : **Cloudflare Pages**
+Déploiement : manuel via CLI
+
+```bash
+npm run build
+npx wrangler pages deploy dist --project-name=expria
+```
+
+Domaine : `expria.app`
+
+## Dépôt lié
+
+Backend : `https://codeberg.org/Hermann_Kitio/expria-backend`