tabatago/CLAUDE.md

TabataGo — CLAUDE.md

Lis ce fichier EN ENTIER avant chaque session. C'est la constitution du projet.

Projet

Application mobile Tabata (iOS + Android) construite avec Expo SDK 52 + Expo Router v3. Modèle freemium via RevenueCat. Analytics via PostHog. Offline-first.

Environnement de développement

Test sur device physique via Expo Go — pas de simulateur iOS.

• Scanner le QR code affiché par npx expo start avec l'app Expo Go sur le téléphone
• Le téléphone et le Mac doivent être sur le même réseau Wi-Fi
• En cas de problème réseau : npx expo start --tunnel (utilise ngrok, plus lent mais fiable)

Contraintes Expo Go à respecter

• Pas de modules natifs custom — uniquement les modules inclus dans le SDK Expo Go
• react-native-purchases (RevenueCat) ne fonctionne PAS dans Expo Go → mocker le paywall en dev, tester sur build EAS uniquement
• expo-notifications fonctionne partiellement dans Expo Go → tester les notifications sur build EAS dev
• Modules compatibles Expo Go SDK 52 (utilisables sans build) : expo-av, expo-haptics, expo-keep-awake, expo-router, expo-secure-store, @react-native-async-storage/async-storage, expo-localization, react-native-posthog

Workflow de test

1. Expo Go → développement UI, timer, audio, exercices (90% du dev)
2. EAS Build (Development) → tester RevenueCat, notifications avancées
3. EAS Build (Production) → build final App Store / Play Store

Stack technique — règles non-négociables

Domaine	Solution	Interdit
Framework	Expo SDK 52 (managed workflow)	Bare workflow sauf si absolument nécessaire
Navigation	Expo Router v3 (file-based)	React Navigation seul
State global	Zustand + AsyncStorage	Redux, MobX, Context pour state global
Timer engine	Date.now() delta dans un hook isolé	setInterval seul (drift inacceptable)
Audio	expo-av avec AVAudioSession	expo-audio (instable), react-native-sound
Paiements	react-native-purchases (RevenueCat)	IAP natif direct — MOCKER en dev Expo Go
Analytics	react-native-posthog	Firebase Analytics, Amplitude
Styles	StyleSheet.create()	Styles inline, Tailwind, NativeWind
Types	TypeScript strict ("strict": true)	any, @ts-ignore sauf justification

Architecture — structure de fichiers

src/
  features/
    timer/
      hooks/useTimerEngine.ts      ← moteur central, AUCUN JSX
      hooks/useTimerSync.ts        ← synchronise audio + exercice sur les events timer
      components/TimerDisplay.tsx  ← affichage uniquement, reçoit tout par props
      components/TimerControls.tsx ← boutons start/pause/stop/skip
      types.ts                     ← TimerPhase, TimerState, TimerConfig
    audio/
      hooks/useAudioEngine.ts      ← gestion expo-av, preload, crossfade
      hooks/useAudioSettings.ts    ← préférences utilisateur (ambiance, volume)
      data/tracks.ts               ← catalogue des tracks (offline)
      data/sounds.ts               ← catalogue des signaux de phase
      types.ts
    exercises/
      hooks/useExercise.ts         ← sélection, navigation entre exercices
      components/ExerciseDisplay.tsx ← rendu selon la phase courante
      components/ExerciseGif.tsx   ← affichage GIF avec fallback
      data/exercises.ts            ← les 38 exercices (offline)
      types.ts
    programs/
      hooks/useProgram.ts
      components/ProgramBuilder.tsx
      data/defaultPrograms.ts
    onboarding/
      hooks/useOnboarding.ts
      screens/                     ← 6 écrans (1 fichier par écran)
    paywall/
      hooks/usePaywall.ts          ← RevenueCat wrapper
      components/PaywallScreen.tsx
  shared/
    components/                    ← Button, Card, Typography, etc.
    hooks/                         ← useHaptics, useKeepAwake, useAppState
    utils/                         ← formatTime, etc.
    constants/                     ← couleurs, durées par défaut
  app/                             ← Expo Router (fichiers de route uniquement)
    (tabs)/
      index.tsx                    ← Home
      history.tsx
      settings.tsx
    timer/index.tsx
    programs/[id].tsx
    onboarding/index.tsx
    paywall/index.tsx

Règles de code

1. Un fichier = une responsabilité — si un hook dépasse 150 lignes, il doit être découpé
2. Toute logique métier dans les hooks — les composants n'ont QUE du JSX + appel de hooks
3. Barrel exports — chaque feature expose un index.ts propre
4. Tests colocalisés — ComponentName.test.tsx dans le même dossier
5. Pas d'effet secondaire dans le render — tout dans useEffect ou les handlers
6. Typage strict des events — pas de any dans les callbacks de timer/audio

Commandes du projet

npx expo start                    # dev — scanner le QR avec Expo Go
npx expo start --tunnel           # si problème réseau Wi-Fi (ngrok)
npx expo start --clear            # vider le cache Metro si comportement bizarre
jest --watchAll                   # tests en continu
eas build --profile development   # build dev (pour tester RevenueCat, notifs)
eas build --platform ios          # build TestFlight
npx expo export                   # bundle production

Comment utiliser les skills

Quand tu travailles sur une feature spécifique, lis le skill correspondant :

• Timer → .claude/skills/timer/SKILL.md
• Audio → .claude/skills/audio/SKILL.md
• Exercices → .claude/skills/exercises/SKILL.md
• Workflow général → .claude/skills/workflow/SKILL.md

Priorité d'implémentation V1

1. useTimerEngine + TimerDisplay (plein écran)
2. useAudioEngine + synchronisation avec timer
3. ExerciseDisplay + données des 38 exercices
4. Synchronisation triple timer × audio × exercice
5. Onboarding 6 écrans + mini-démo live
6. Paywall RevenueCat
7. Streak + historique
8. Notifications de rappel