Architecture de la plateforme

Le Clos des Eucalyptus sépare l’expérience web de l’API métier. Les deux dépôts sont déployables indépendamment, mais partagent un contrat HTTP et un workflow de livraison coordonné.

Responsabilités des dépôts

Sujet	harmony-web	harmony-backend
Site public et back-office	rendu SvelteKit	données et règles métier
Session navigateur	cookie httpOnly et redirections	validation du token et du second facteur
API publique	BFF adapté aux écrans	contrat et implémentation HTTP
Persistance	aucune base métier	PocketBase et migrations
Présentation	Svelte, view models, Storybook	DTO JSON uniquement
Documentation	portail Starlight et Scalar	sources techniques et OpenAPI

Frontière navigateur–serveur

Le navigateur n’appelle pas directement le backend externe. Une page utilise un load serveur, une form action ou une route BFF SvelteKit. Cette couche :

• récupère les cookies httpOnly ;
• ajoute le token au seul appel serveur vers l’API ;
• transforme les réponses en données nécessaires à l’écran ;
• masque les secrets et champs privilégiés au bundle client.

Une exception n’est acceptable que pour une ressource explicitement publique et non sensible ; la convention du projet reste de passer par SvelteKit afin de garder une frontière homogène.

Flux d’une lecture publique

GET /apartments/villa-marine
  → +page.server.ts
  → GetApartmentBySlugUseCase
  → ApartmentHttpRepository
  → GET backend /api/apartments/villa-marine?locale=fr
  → entité Apartment
  → ApartmentViewModel
  → composant Svelte rendu côté serveur

Flux d’une mutation back-office

formulaire navigateur
  → form action SvelteKit
  → contrôle locals.backOfficeUser + rôle
  → cas d’usage authentifié créé pour cette requête
  → API backend avec Authorization: Bearer …
  → validation + autorisation backend
  → service de domaine
  → repository PocketBase
  → message français prêt à afficher

Les deux contrôles d’autorisation sont nécessaires. La visibilité d’un bouton et le guard du layout ne remplacent ni le contrôle de l’action SvelteKit ni celui de l’API.

Dépendances internes

Les deux dépôts appliquent une architecture orientée domaine :

présentation / API  ──→  application / services  ──→  domaine
infrastructure      ───────────────────────────────→  ports du domaine

Le domaine ne connaît ni SvelteKit, ni PocketBase, ni fetch, ni un SDK fournisseur. Les détails externes implémentent des ports définis vers l’intérieur.

Contrat partagé

backend/docs/openapi.yaml est la source de vérité des endpoints publics et back-office. Il décrit les paramètres, authentifications, corps, réponses et erreurs. Le portail web le copie lors du build et Scalar le rend dans la référence interactive.

Le contrat de code TypeScript dans web/src/lib/infrastructure/**/**.types.ts est un consommateur, pas une seconde source de vérité. Une divergence doit être corrigée dans le même lot.

Données multilingues

Le backend stocke les traductions séparément des entités et accepte ?locale=xx sur les endpoints localisés. Le frontend public choisit la locale avec Paraglide puis la transmet aux cas d’usage. Le back-office charge la liste des langues actives et édite un dictionnaire indexé par code de locale.

La langue source et la stratégie de fallback sont des règles métier backend ; la forme et le compteur « 3 / 5 langues » sont de la présentation frontend.

Services asynchrones

Certaines fonctions sortent du simple cycle requête/réponse :

• imports et variantes de médias ;
• synchronisation de calendriers externes ;
• notifications métier et e-mails ;
• flux SSE de notifications du back-office ;
• appels d’IA optionnels et audités.

Le backend possède l’état et la reprise. Le frontend affiche un statut, écoute ou interroge un endpoint BFF et permet une relance contrôlée. Il ne réimplémente pas le worker dans le navigateur.

Compatibilité cross-stack

Une évolution coordonnée doit permettre un ordre de déploiement sûr :

1. privilégiez une réponse additive ;
2. déployez le backend compatible avec l’ancien frontend ;
3. déployez le frontend qui consomme le nouveau champ ;
4. retirez l’ancien comportement dans un lot ultérieur.

Un renommage ou une suppression de champ demande une phase de compatibilité. Les branches portent le même suffixe, les PR sont liées et les E2E sont exécutés avec les deux révisions attendues.

Sources de vérité

Information	Source
Schéma HTTP	backend/docs/openapi.yaml
Schéma PocketBase	backend/migrations/
Règles métier	domain/ du dépôt propriétaire
Assemblage frontend	web/src/lib/container.ts
Assemblage backend	backend/main.go
Traductions publiques	web/messages/*.json
Composants et états visuels	stories Storybook
Procédures produit et techniques	portail Starlight