# Architecture

## Trois clients, un backend

| Client | Auth | Routes | Contrôleurs |
|---|---|---|---|
| Application mobile | JWT (`auth:api`) | `routes/api.php` → `/api/...` | `App\Http\Controllers\API\*` |
| Espace Blade | Session (`auth` + `adminOrManager`) | `routes/web.php` → `/admin/...` | `App\Http\Controllers\Admin\*` |
| Back-office React | JWT (`auth:api` + `EnsureReactAdmin`) | `routes/react.php` → `/api/react/...` | `App\Http\Controllers\React\*` |

## Règles de séparation

* **Mobile et Blade ne dépendent pas de React.** `routes/react.php` est chargé par `ReactApiServiceProvider` (déclaré dans `bootstrap/providers.php`) ; supprimer cette ligne désactive entièrement l'API React sans toucher au reste.
* Les contrôleurs React ne contiennent pas de règles métier propres : ils lisent les mêmes modèles (`Visit`, `User`, `Listing`…) et réutilisent `App\Services\DelegueAnalyticsService`. La traduction base ↔ front (snake_case → camelCase, libellés de rôles/statuts) est centralisée dans `App\Support\React\Mapper`.
* Les migrations React sont **additives** : colonnes nullables / valeurs par défaut sur `cities`, `listings`, `deplacements`, et quatre tables préfixées `react_` (planification, secteurs). Aucune table existante n'est renommée ni supprimée.
* Réponses de l'API React : `{ "data": … }` ; erreurs : `{ "message": …, "errors": … }`.

## Rôles

| Base (`users.role`) | Mobile | Blade | React |
|---|---|---|---|
| `admin` | — | oui | oui (accès complet) |
| `manager` | — | oui | oui |
| `delegue`, `visitor` | oui | non | non |

## Front React (`frontend/admin`)

`repositoryFactory` choisit l'implémentation : `VITE_DATA_SOURCE=api` → `src/services/api/*` (axios, jeton Bearer) ; `mock` → `src/mocks/*`.
Les modules « plateforme SaaS » (entreprises, plans, abonnements, journaux, monitoring, support) n'ont pas d'équivalent Laravel et restent en démonstration.

## Points d'attention de sécurité

* Une clé Google Maps est écrite en dur dans une vue Blade (`resources/views/pages/users/tracking*`). La déplacer dans `.env`/`config/services.php` et la **restreindre par référent HTTP** dans Google Cloud.
* Ne pas committer `.env` (déjà ignoré).

## Anomalies déjà présentes dans le code d'origine (non corrigées volontairement)

Constatées en important le projet ; elles n'ont aucun lien avec l'API React et n'ont pas été modifiées :

1. `routes/api.php` référence `App\Http\Controllers\API\WorkSessionController` (routes `/work/start` et `/work/end`), mais ce fichier n'existe pas dans l'archive reçue : seul un squelette `App\Http\Controllers\WorkSessionController` (sans `start`/`end`) existe. À vérifier sur votre serveur actuel (la version en production est peut-être plus récente).
2. `app/Http/Controllers/API/ExpenseDashboardController.php` déclare `namespace App\Http\Controllers\Api` (casse différente de `API`) : sur Linux (sensible à la casse), la route `/expense-dashboard` ne trouve pas la classe. Correction : remplacer la ligne `namespace` par `App\Http\Controllers\API` (et ajouter `use App\Http\Controllers\Controller;` si absent).
3. `routes/web.php` et `routes/api.php` contiennent des fonctions anonymes : `php artisan route:cache` est donc impossible (non utilisé par `deploy.sh`). `php artisan route:list` signalera aussi les points 1 et 2 tant qu'ils ne sont pas corrigés.