doc: add architecture/decoupage-organisation.md

Documents the per-project layout under src/ (Abstract, Server, Org, Api, Blogs, Web, Org.Tests) as one of the two remaining items of Jalon 0 in ROADMAP.md: 'Decoupage Yavsc.Org vs Yavsc.Server vs Yavsc.Api clarifie dans l'Architecture' The page is referenced from the new doc/README.md index, and will also be linked from CONTRIBUTING.md in the next commit.
2026-06-27 14:52:28 +01:00 · 2026-06-27 14:52:28 +01:00 · 91bd97c3fd
commit 91bd97c3fd
parent 989cca669f
2 changed files with 85 additions and 0 deletions
--- a/doc/README.md
+++ b/doc/README.md
@ -15,6 +15,7 @@ La racine de l'architecture est [Architecture.md](Architecture.md).
 | [architecture/dictionnaires-metier.md](architecture/dictionnaires-metier.md) | Dictionnaires métier, héritage en arbre, cycle de vie d'un terme |
 | [architecture/offres-frontmatter.md](architecture/offres-frontmatter.md) | Offre fournisseur, ClasseFormulaire, ClasseDevis, parsing frontmatter |
 | [architecture/postit-oidc.md](architecture/postit-oidc.md) | Client desktop PostIt, custom URI scheme, silent refresh |
+| [architecture/decoupage-organisation.md](architecture/decoupage-organisation.md) | Découpage des projets .NET (Abstract, Server, Org, Api, Blogs, Web, Org.Tests) |

 ## Roadmap & design exploration

--- a/doc/architecture/decoupage-organisation.md
+++ b/doc/architecture/decoupage-organisation.md
@ -0,0 +1,84 @@
+# Découpage des projets .NET
+
+> **Récapitulatif** : Le code est réparti en sept projets .NET
+> sous `src/`, organisés par rôle : domaine partagé, bibliothèque
+> métier, front web utilisateur-facing, API REST, blog, front admin,
+> et tests. Détail dans cette page, racine de l'architecture :
+> [Architecture.md](../Architecture.md).
+
+## Vue d'ensemble
+
+```
+                     ┌──────────────────────────────┐
+                     │ Yavsc.Abstract (lib)         │
+                     │ Modèles du domaine partagés  │
+                     └──────────────┬───────────────┘
+                                    │
+                     ┌──────────────▼───────────────┐
+                     │ Yavsc.Server (lib)           │
+                     │ Helpers, EF, services        │
+                     └──────┬───────────────┬───────┘
+                            │               │
+              ┌─────────────▼──┐    ┌───────▼────────────┐
+              │ Yavsc.Org (web)│    │ Yavsc.Api (web)    │
+              │ Front web      │    │ API REST JSON      │
+              │ + Identity-    │    │ JwtBearer          │
+              │   Server       │    │                    │
+              │ + Razor views  │    └────────────────────┘
+              └────────────────┘
+                            │
+                     ┌──────▼────────────────────────────┐
+                     │ Yavsc.Blogs (web)                 │
+                     │ Front web spécifique au blog      │
+                     │ (consomme Yavsc.Server)           │
+                     └───────────────────────────────────┘
+
+Clients externes :
+  - Yavsc.Web  : front admin / expérimentation, JwtBearer.
+  - PostIt     : client desktop Avalonia (cf. postit-oidc.md).
+```
+
+## Par projet
+
+| Projet             | Type SDK       | Rôle                                                                                          |
+|--------------------|----------------|-----------------------------------------------------------------------------------------------|
+| `Yavsc.Abstract`   | Library        | Modèles du domaine partagés (entités, value objects, enums). Pas de dépendance framework.     |
+| `Yavsc.Server`     | Library        | Bibliothèque métier : `DbContext`, helpers PayPal/SMTP, services métier, modèles billing/blog. |
+| `Yavsc.Org`        | ASP.NET Web    | Front web utilisateur-facing : Razor views, IdentityServer8 (OP), AccountController, Razor.   |
+| `Yavsc.Api`        | ASP.NET Web    | API REST JSON consommée par les clients externes (PostIt, …). JwtBearer auth.                |
+| `Yavsc.Blogs`      | ASP.NET Web    | Sous-domaine front web spécifique au blog, autonome mais consomme `Yavsc.Server`.            |
+| `Yavsc.Web`        | ASP.NET Web    | Front admin / expérimentations, JwtBearer, référence `Yavsc.Abstract` et `Yavsc.Server`.    |
+| `Yavsc.Org.Tests`  | Test (xUnit)   | Tests d'isolation du front web (`Yavsc.Org`) — fakes, controller tests.                     |
+
+## Pourquoi ce découpage
+
+- **`Yavsc.Abstract` séparé de `Yavsc.Server`** : permet aux clients
+  externes (PostIt — projet Avalonia sous `src/PostIt/`) de partager
+  les modèles DTO sans embarquer Entity Framework ni ASP.NET Core.
+- **`Yavsc.Server` est une library, pas un web host** : on peut
+  tester les services sans démarrer Kestrel ; plusieurs fronts
+  (Org, Api, Blogs) consomment les mêmes helpers sans dupliquer.
+- **`Yavsc.Api` séparé de `Yavsc.Org`** : l'API REST est destinée
+  aux clients headless (PostIt, intégrations tierces) ; elle n'a
+  pas besoin des vues Razor ni d'IdentityServer. Inversement, le
+  front web peut servir ses propres pages serveur sans exposer
+  une API REST.
+- **`Yavsc.Blogs` séparé** : le blog a son propre cycle de vie
+  (déploiement, modèle de contenu) tout en réutilisant le contexte
+  EF de `Yavsc.Server`.
+
+## Conséquences pratiques
+
+- Une modification d'un modèle DDD dans `Yavsc.Abstract` peut
+  casser **plusieurs fronts à la fois** (Org, Api, Blogs, Web).
+  C'est attendu ; les tests de `Yavsc.Org.Tests` doivent suivre.
+- Ajouter une route API dans `Yavsc.Api` n'implique pas de
+  recompiler `Yavsc.Org` (et inversement).
+- `PostIt` (sous `src/PostIt/`) ne référence que `Yavsc.Abstract` ;
+  il n'embarque ni EF ni ASP.NET Core.
+
+## Voir aussi
+
+- [Architecture.md](../Architecture.md) — racine.
+- [postit-oidc.md](postit-oidc.md) — PostIt consomme `Yavsc.Api`
+  via OIDC.