# 01 — Architecture

> Vue d'ensemble technique. Le détail multi-tenant vit dans [`docs/ARCHITECTURE_MULTITENANT.md`](../portail-manager/docs/ARCHITECTURE_MULTITENANT.md) (référence normative) ; ce document en donne la synthèse et le cadrage global.

## Stack

- **Backend / API** : Symfony 6.4, PHP 8.1+, Doctrine ORM 3 / DBAL 4.
- **Base de données** : MariaDB 10.11 / MySQL 8 (le code cible les deux).
- **Auth API** : `lexik/jwt-authentication-bundle` (JWT RS256, TTL 6 h) + refresh tokens (7 j, rotation).
- **CORS** : `nelmio/cors-bundle` (prêt PWA : `ngsw-bypass`, en-têtes d'expiration exposés).
- **Async** : `symfony/messenger` (transport Doctrine ; `MESSENGER_MODE` sync/async).
- **Front admin** : Twig + Tailwind + Flowbite + Hotwired (Turbo/Stimulus).
- **Front client** : **PWA Ionic** (fournie ultérieurement) consommant l'API.
- **Sites e-commerce clients** (futur) : Symfony sur le même socle, branchés sur la base projetée du client.

## Modèle multi-tenant retenu

**Base centrale autoritaire + projection POS par client.**

```
                    ┌─────────────────────────────────────────┐
                    │      BASE CENTRALE (yima-shop)           │
                    │  SOURCE DE VÉRITÉ — toutes les données   │
                    │  • boutiques, users, RBAC, sécurité      │
                    │  • catalogue, stock, ventes, caisse…     │
                    │  • company_database (connexions chiffrées)│
                    └───────────────┬─────────────────────────┘
                                    │ synchronisation (Messenger)
                 ┌──────────────────┴───────────────────┐
                 ▼ (canal A)                             ▼ (canal B)
        ┌───────────────────────┐            ┌──────────────────────────┐
        │ base client projetée  │            │ WooCommerce du client     │
        │ (ex. amansa)          │            │ (WordPress existant)      │
        │ PROJECTION POS lecture│            │ via API REST WooCommerce  │
        └───────────┬───────────┘            └────────────┬─────────────┘
                    ▼                                      ▼
        Site e-commerce Symfony (futur)          Site WordPress/WooCommerce
```

- **Écritures métier** : au centre (POS via API) — source de vérité.
- **Canal A — base client projetée** (clients **sans** site) : reçoit une **projection en lecture** d'un sous-ensemble POS → site e-commerce Symfony. Jamais autoritaire.
- **Canal B — connecteur WooCommerce** (clients **avec** un WordPress/WooCommerce) : push produits/prix/stock vers **leur** WooCommerce, pull des commandes → POS central ([fiche](modules/woocommerce-connector.md), [ADR-007](notes/decisions.md)).
- **Synchronisation** : événements de domaine via Messenger (recommandé), voir [`ARCHITECTURE_MULTITENANT.md` §4bis](../portail-manager/docs/ARCHITECTURE_MULTITENANT.md).

## Couches applicatives

```
Contrôleurs (Web Twig / API JSON)
        │  (IsGranted, PermissionVoter, ApiResponseFormatter)
Services métier (POS, Catalogue, Stock, Caisse…)
        │  (EntityManagerService safe methods, FileLogger)
Doctrine ORM  ──►  Base centrale (EM par défaut)
        │
TenantConnectionService  ──►  Bases clients (DriverManager, à la demande)
```

- **Autorisation** : `PermissionResolver` central (permissions `<domaine>.<action>`), voters (`PermissionVoter`, `CompanyVoter` en délégation).
- **Accès DB sûr** : toujours via `EntityManagerService` (transactions, retry, health).
- **Connexions clients** : `TenantConnectionService` (chiffrement du mot de passe, `DriverManager`).
- **Journalisation & alertes** : `FileLogger` + `AlertDeduplicationService` (anti-spam).

## Surfaces d'entrée

| Surface | Firewall | Auth | Usage |
|---|---|---|---|
| `/` (portail web) | `main` | form_login + remember-me | Admin/Manager |
| `^/api` | `api` (stateless) | JWT Bearer | PWA / intégrations |
| `^/api/mobile/*` | `api` | JWT + `X-Device-UID` | PWA device-bound (contrôleurs à écrire) |
| `^/api/login*` | public | — | Login/2FA/refresh |

## Découpage en modules

Chaque capacité métier est un **module** documenté ([modules/](modules/README.md)) : entités, permissions, endpoints API, écrans, règles, tests, et impact sur la projection e-commerce. Les modules partagent les fondations transverses (RBAC, chiffrement, connexions, journalisation).

## Environnements

| Env | Base | Particularités |
|---|---|---|
| dev | `yima-shop` | `.env.local` (secrets), fixtures |
| test | `yima-shop_test` | clés JWT dédiées, `ENABLE_TOKEN_SECURITY_VALIDATION=false`, seeds idempotents |
| prod | `.env.prod.local` | clés/secret dédiés, `MESSENGER_MODE=async` recommandé |

## Qualité & exploitation

- **Tests** : unit (mocks) + fonctionnels (WebTestCase) — voir [06 — Plan de tests](06-plan-de-tests.md).
- **Observabilité** : logs datés `var/logs/`, alertes email dédupliquées, détection proactive de menaces.
- **Sauvegardes** : `DatabaseBackupService` (central) → à généraliser par tenant (roadmap phase 2).

## Suite

Modèle de données : [02 — Modèle de données](02-modele-de-donnees.md).