FamilyPlanner/README.md

# Family Planner Hub

Family Planner Hub est un socle applicatif pour orchestrer les emplois du temps et l environnement d une fratrie. Le depot fournit l infrastructure initiale pour:

- collecter des plannings pour chaque enfant (PDF, image, tableur),
- analyser ces documents via un service d ingestion et d OCR pour extraire les activites,
- centraliser les evenements dans une API,
- proposer une interface multi ecran claire, avec navigation plein ecran en un clic,
- generer des notifications et des alertes autour des activites remarquables (sport, sorties, examens, etc.).

## Apercu de l architecture

```
family-planner/
|-- backend/                # API Express + services metiers
|-- frontend/               # Application React (Vite + TypeScript)
|-- ingestion-service/      # Service Python pour OCR et parsing de plannings
|-- shared/                 # Bibliotheques partagees (types TS, composants UI)
|-- config/                 # Fichiers de configuration multi environnement
|-- docs/                   # Documentation produit, technique et parcours utilisateurs
`-- README.md
```

### Flux cible

1. L utilisateur ajoute un enfant et charge un planning (drag-and-drop ou selection, PDF/PNG/JPEG/XLSX).
2. Le frontend envoie le document au backend.
3. Le backend stocke le fichier puis delegue l analyse au service `ingestion-service`.
4. Le service OCR produit un schema canonical d activites et le renvoie a l API.
5. L API persiste le planning, calcule les evenements cle et alimente le UI.
6. Le UI affiche la semaine par enfant, signale les alertes et permet un affichage plein ecran.

## Capacites cibles

- Multi-enfants illimites avec profils individuels.
- Synchronisation journaliere/semaine + vue agenda familiale.
- Gestion des alertes (push navigateur, emails ou autres adaptateurs).
- Mode plein ecran simple.
- Support de plusieurs ecrans (responsive + casting web).
- Authentification familiale minimale (a definir).

## Stack technique

### Frontend (`frontend/`)

- Vite + React + TypeScript.
- Styled Components (placeholder) pour le theming dynamique.
- React Query pour la gestion des appels API.
- Architecture modulable: `screens/`, `components/`, `services/`, `styles/`.

### Backend (`backend/`)

- Node.js 20 + Express + TypeScript.
- Prisma (optionnel, non configure) comme ORM cible.
- Architecture hexagonale legere (routes -> controllers -> services -> models).
- Gestion des evenements via un bus simple (placeholder).

### Ingestion (`ingestion-service/`)

- Python 3.11.
- FastAPI expose des endpoints internes.
- Pydantic pour les schemas.
- Support d OCR via Tesseract (a integrer).
- Pipelines modulaires (parser PDF, parser image, parser tableur).

### Shared packages (`shared/`)

- `shared/types`: definitions TypeScript communes (DTO, schemas).
- `shared/ui`: composants React reutilisables (design system leger).

## Prise en main

### 1. Installer les dependances

```bash
# Frontend
cd frontend
npm install

# Backend
cd ../backend
npm install

# Ingestion
cd ../ingestion-service
pip install -e .[dev]
```

### 2. Variables d environnement

Creer un fichier `.env` dans chaque package (voir `config/`) pour configurer les secrets ou URLs.

### 3. Lancer les applications

**🎯 MÉTHODE SIMPLE (Recommandé) :**

Double-cliquez sur :
```
START.bat
```

Ou manuellement :

```bash
# Terminal 1 - Backend (port 5000)
cd backend
npm run dev

# Terminal 2 - Frontend (port 5173)
cd frontend
npm run dev

# Terminal 3 - Ingestion service (optionnel, port 8000)
cd ingestion-service
uvicorn ingestion.main:app --reload
```

**⚠️ IMPORTANT** : Attendez 30 secondes que tout compile avant d'ouvrir le navigateur.

### 4. Ouvrir l'application

1. Ouvrez votre navigateur sur **http://localhost:5173**
2. Appuyez sur **Ctrl + Shift + R** pour vider le cache
3. Créez un profil enfant ou sélectionnez-en un
4. Dans "Congés scolaires", vous pouvez maintenant sélectionner **Monaco** 🇲🇨

### 5. Arrêter les serveurs

Double-cliquez sur :
```
STOP.bat
```

Ou fermez simplement les fenêtres de terminal.

## 🇲🇨 Monaco - Calendrier Scolaire

Family Planner intègre désormais les **vacances scolaires et jours fériés de Monaco** !

**Régions disponibles :**
- Zone A, B, C (France métropolitaine)
- Corse
- **Monaco** 🇲🇨 (avec jours fériés spécifiques)
- DOM-TOM (Guadeloupe, Guyane, Martinique, Réunion, Mayotte)

**Jours fériés spécifiques à Monaco :**
- Sainte Dévote (27 janvier)
- Fête du Prince (19 novembre)
- Fête-Dieu (juin)

**Sources officielles :**
- Arrêté ministériel n° 2023-221 du 18 avril 2023
- Gouvernement Princier de Monaco

Voir [PORTS.md](PORTS.md) pour la configuration des ports.

## Documentation

- `docs/architecture.md`: diagramme haut niveau, flux de donnees, choix techniques.
- `docs/product-vision.md`: besoins utilisateurs, priorites fonctionnelles, feuille de route.
- `docs/data-contracts.md`: schemas partageables entre services (DTO, payloads).
- `docs/ux-flow.md`: wireframes textuels, parcours utilisateur, interactions cle.
- `docs/archive/`: documentation historique et notes de développement.
- **[PORTS.md](PORTS.md)** : Configuration complète des ports utilisés.

## Plan de developpement suggere

1. **Onboarding**: terminer le design system minimal, definir les couleurs et la grille.
2. **Persistence**: brancher une base SQLite/PostgreSQL via Prisma, ajouter migrations.
3. **Import OCR**: connecter Tesseract ou un provider cloud, creer les pipelines de parsing.
4. **Alertes**: implementer la logique de detection (regex mots cle, categories).
5. **Multi-devices**: ajouter PWA/offline, ecran TV, application mobile (React Native ou Tauri).

## Scripts racine

Le fichier `package.json` racine declare des scripts d orchestration (install, lint, test). Voir la section suivante pour plus de details.

## Licence

En attente de definition (placeholder). Ajouter la licence familiale ou open-source adaptee lorsque le projet sera partage.