# Architecture Coffra

## Principes

1. **Règles métier et autorisation** : implémentées côté **Laravel** (services, policies, middleware, validation). Le client ne fait que refléter les habilitations pour l’UX.
2. **React** : présentation, navigation mobile-first, appels API, gestion d’état UI locale (formulaires, listes).
3. **Découpage par domaines métier** : dossiers dédiés côté backend (`app/Domains/...`) et frontend (`src/domains/...`), avec un noyau partagé (`Core`, `shared`).
4. **Multi-organisation** : les données métier sont conçues pour être **isolées par `organization_id`**. En MVP, une seule organisation est utilisée en pratique, mais le schéma et les modèles (`Organization`, rattachement `User` / `Worker`) sont prêts pour plusieurs tenants.
5. **Scope d’accès** : les **abilities** (chaînes globales par rôle) constituent une couche simple pour le middleware et l’UI. **L’accès réel** aux ressources devra toujours être **restreint par organisation**, puis par **chantier / projet** (policies, scopes Eloquent, filtres de requête), une fois les modules métier en place.
6. **Module Présences (`Attendance`)** : spécifié pour implémentation — ressource rattachée à **`project_id`** + **`worker_id`** ; saisie par **User** ; validation réservée **chef / entrepreneur** ; base paie **`daily`** / **`hourly`** uniquement. Contrat **`API_SPEC.md` §11** ; le domaine dossier `Presence/` pourra héberger services / actions dédiées lors du codage.

## Backend (Laravel)

```
app/
  Domains/
    Auth/          # Contrôleurs et requêtes HTTP d’authentification
    Core/          # Enum rôles MVP, registre d’habilitations, middleware `ability`
    Chantier/      # Réservé — pas encore implémenté
    Presence/      # Réservé
    Besoin/        # Réservé
    Ouvrage/       # Réservé
    Paiement/      # Réservé
  Models/          # Eloquent : User, Organization, Worker, …
routes/
  api.php          # Préfixe global : api/v1 (configuré dans bootstrap/app.php)
```

- **Sanctum** : jetons d’API pour la SPA (comptes **User** uniquement ; pas de connexion ouvrier dans le MVP).
- **Middleware `ability:{nom}`** : vérifie une habilitation dérivée du rôle utilisateur (`EnsureUserCan`). Ne remplace pas le filtrage par `organization_id` / chantier.
- **CORS** : `config/cors.php` (chemins `api/*`). À resserrer en production (`allowed_origins` explicites, credentials si besoin).

### Isolation multi-org (cible)

- Toute table métier future devra inclure `organization_id` (ou équivalent) et être interrogée via scopes / policies tenant-aware.
- Les utilisateurs (`users`) sont rattachés à une organisation ; les **workers** (ouvriers terrain sans compte) le sont également.

## Frontend (React)

```
src/
  app/             # App shell, routeur
  domains/
    auth/          # Contexte d’auth, page de connexion
    layout/        # Layout principal (header + bottom nav)
    core/          # Tableau de bord, profil, placeholders modules
    presence|besoin|ouvrage|paiement/  # Réservés (.gitkeep)
  shared/lib/      # Client HTTP (`apiFetch`)
  styles/          # Tailwind (entrée `@import "tailwindcss"`)
```

- **React Router** : routes publiques (`/login`) et zone connectée avec layout commun.
- **`can(ability)`** : basé sur le tableau `abilities` renvoyé par `/auth/me` (cohérent avec le backend, mais **non substitut** aux contrôles API ni au scope org / chantier).
- **Chantier actif** : le shell doit évoluer vers un **contexte de chantier / projet courant** (sélecteur dans l’en-tête ou l’accueil) — voir `SCREEN_SPEC.md`. Les données affichées devront être cohérentes avec ce contexte et avec les réponses API scoped.

## Flux d’authentification (MVP)

```mermaid
sequenceDiagram
  participant SPA as Frontend
  participant API as Laravel API
  SPA->>API: POST /api/v1/auth/login
  API-->>SPA: user + organization + abilities + token
  SPA->>SPA: stocke token
  SPA->>API: GET /api/v1/auth/me (Bearer)
  API-->>SPA: user + organization + abilities
```

Pas d’inscription publique : les **User** sont créés par seed, outil d’administration ou invitation (à venir).

## Évolutions prévisibles

- Ressources **Chantier / Projet**, rattachement des utilisateurs et filtrage systématique des requêtes.
- **platform_admin** (hors périmètre MVP fonctionnel) : rôle transverse multi-org réservé à une future console plateforme.
- Passage à une table `roles` / `permissions` si la granularité dépasse l’enum MVP.
- Files d’attente et notifications lorsque les modules métier seront actifs.