smart_ide/services/docv/enso-docs/ARCHITECTURE_DOCV_DETAILLEE.md

Architecture logicielle détaillée — docv

Proposition d’architecture logicielle détaillée pour le socle docv (agnostique métier), consommée par enso. Ce document complète docs/ARCHITECTURE_DOCV_ENSO.md en se limitant au périmètre docv.

---

1. Rôle et périmètre de docv

• Rôle : socle commun contenant tout le code applicatif (back et front) agnostique du métier côté périmètre avocat. Le projet enso configure ce socle et n’ajoute que des spécifiques validés.
• Périmètre : authentification, offices, utilisateurs, rôles et permissions, dossiers (folders), documents, types de documents et de dossiers, partage et invitations, notes et rappels, textes i18n, configuration système (écrans, actions, options), ancrage et IA consommés côté back uniquement.
• Hors périmètre docv : IdNot, API notaire, Mailchimp, OVH, Stripe, écrans et flux métier spécifiques avocat ou notaire (listés dans docs/features/SPECIFIQUES_PROJETS.md).

---

2. Vue d’ensemble des couches

┌─────────────────────────────────────────────────────────────────────────┐
│  docv-front (Next.js / React, TypeScript)                               │
│  ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌─────────────────┐  │
│  │ Pages/App   │ │ Components   │ │ API client  │ │ Design system   │  │
│  │ (routes)    │ │ (UI, layout) │ │ (backend)   │ │ + i18n           │  │
│  └──────┬──────┘ └──────┬───────┘ └──────┬──────┘ └────────┬────────┘  │
│         │               │                │                  │           │
│         └───────────────┴────────────────┴──────────────────┘           │
│                                    │ HTTP (JSON)                         │
└────────────────────────────────────┼────────────────────────────────────┘
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  docv-back (Rust: Axum ou Actix)                                         │
│  ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌─────────────────────┐  │
│  │ Handlers    │→│ Services    │→│ Repositories│→│ DB + clients       │  │
│  │ (HTTP)      │ │ (métier)    │ │ (accès BDD)│  │ (ancrage, IA)      │  │
│  └─────────────┘ └──────────────┘ └─────────────┘ └─────────────────────┘  │
│         │                │                │                    │         │
│  ┌──────┴────────────────┴────────────────┴────────────────────┐      │
│  │ Middleware: auth, logging, CORS, rate limit, erreurs            │      │
│  └───────────────────────────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────────────────────────┘
         │                    │
         ▼                    ▼
┌─────────────────┐  ┌────────────────────────────────────────────────────┐
│ PostgreSQL      │  │ API externes (back uniquement): ancrage, IA           │
│ (docv BDD)      │  │ (serveur services / api-anchorage ; sous-module ai)   │
└─────────────────┘  └────────────────────────────────────────────────────┘

• Front : ne parle qu’au backend docv ; pas d’appel direct aux API externes.
• Back : orchestre la logique métier, la BDD et les clients HTTP vers l’ancrage et l’IA.
• Partagé : docv-shared (Rust, natif + WASM) pour validation, formatage, constantes ; optionnellement docv-core (TS) pour types et contrats API.

---

3. Backend (docv-back)

3.1 Structure des répertoires

docv-back/
├── Cargo.toml
├── .env.example
├── migrations/
├── seeds/
└── src/
    ├── main.rs              # Bootstrap, routes, middleware
    ├── config/              # Chargement env, config app et DB
    ├── db/                  # Pool connexions, run migrations
    ├── error/               # Types erreur, impl IntoResponse / From
    ├── handlers/            # Contrôleurs HTTP (entrée/sortie uniquement)
    ├── services/            # Logique métier (orchestration)
    ├── repositories/        # Accès données (requêtes SQL / ORM)
    ├── models/              # Entités et DTOs (sérialisation)
    ├── middleware/          # Auth, logging, CORS, rate limit
    ├── clients/             # Clients HTTP externes (anchoring, ia)
    └── routes.rs            # Agrégation des routes

3.2 Responsabilités par couche

Couche	Rôle	Exemples
handlers	Recevoir la requête HTTP, valider les entrées (form/body), appeler le service, renvoyer la réponse (JSON ou erreur). Pas de logique métier ni de SQL.	auth.rs (login, logout), folders.rs (CRUD), documents.rs, system_configuration.rs, screen_config.rs, action_config.rs
services	Logique métier : règles, orchestration, appels aux repositories et aux clients externes (ancrage, IA). Pas d’accès direct à la requête HTTP.	auth_service, folder_service, document_service, parametrage_service (résolution écrans/actions/options), anchoring, ia
repositories	Requêtes SQL (ou ORM) et mapping vers les modèles. Pas de règles métier.	user_repository, folder_repository, document_repository, screen_config_repository
models	Structures de données (entités BDD, DTOs requête/réponse). Sérialisation / désérialisation (serde).	User, Folder, Document, ScreenConfig, ActionConfig
clients	Appels HTTP sortants vers l’API d’ancrage (serveur services, api-anchorage) et l’API IA (sous-module ai). Erreurs typées, pas de fallback silencieux.	anchoring_client, ia_client
middleware	Auth (JWT ou session), logging structuré, CORS, rate limit, centralisation des erreurs.	auth_middleware, logging_middleware, error_handler
config	Lecture des variables d’environnement et construction de la config (DB URL, secret JWT, URLs ancrage/IA, feature flags).	Config, load_from_env
error	Types d’erreur métier et techniques ; impl From et IntoResponse pour un retour HTTP cohérent.	AppError, AuthError, NotFoundError

3.3 Ressources API (principales)

• Auth : POST /auth/login, POST /auth/logout, GET /auth/me, éventuellement refresh.
• Offices : GET /offices, GET /offices/:id, PUT /offices/:id (selon droits).
• Users : GET /users, GET /users/:id, PUT /users/:id (selon droits).
• Roles : GET /roles, GET /roles/:id, POST /roles, PUT /roles/:id (admin).
• Folders : GET /folders, GET /folders/:id, POST /folders, PUT /folders/:id, DELETE /folders/:id, GET /folders/archived, GET /folders/deleted.
• Documents : GET /folders/:folderId/documents, POST /folders/:folderId/documents, GET /documents/:id, PUT /documents/:id, DELETE /documents/:id, upload/download.
• Document types : GET /document-types, POST /document-types, GET /document-types/:id, PUT /document-types/:id.
• Folder types (case types) : GET /folder-types, POST /folder-types, GET /folder-types/:id, PUT /folder-types/:id.
• Site texts (i18n) : GET /site-texts (filtré par clé, locale), PUT /site-texts (admin).
• System configuration : GET /system-configuration, PUT /system-configuration (admin), clés masquées pour les valeurs sensibles.
• Paramétrage écrans/actions : GET /screen-config, GET /action-config (résolus par office/rôle/type de dossier) ; PUT /screen-config, PUT /action-config (admin).
• Ancrage : pas d’endpoint direct front ; le back appelle l’API ancrage dans les services (ex. à la validation d’un document).
• IA : pas d’endpoint direct front ; le back appelle l’API IA dans les services (ex. extraction, chat, synthèse). Référence : docs/features/IA_GRANDS_PRINCIPES.md.

3.4 Base de données (PostgreSQL)

• Migrations : versionnées (ex. SQLx ou Diesel), appliquées au démarrage ou via une commande dédiée.
• Seeds : rôles par défaut, matrice de permissions, types de documents/dossiers, textes site, configuration système (écrans, actions, options), données de démo optionnelles.
• Entités principales (agnostiques) : users, contacts, addresses, offices, office_members, roles, role_permissions, folders, folder_types, documents, document_types, site_texts, system_configuration, screen_config, action_config, folder_share, invitations, notes, reminders. Pas de champs IdNot ou notaire dans le noyau docv.

3.5 Clients externes (back uniquement)

• Ancrage : client HTTP vers le serveur services (infra 4NK), projet api-anchorage. Appel depuis un service (ex. après validation d’un document) ; résultat stocké ou renvoyé dans la réponse métier.
• IA : client HTTP vers l’API du sous-module ai (TypeScript, socle Ollama/AnythingLLM). Appel depuis un service (extraction, chat, synthèse) ; jamais exposé directement au front. Référence : docs/features/IA_GRANDS_PRINCIPES.md.

---

4. Frontend (docv-front)

4.1 Structure des répertoires

docv-front/
├── package.json
├── tsconfig.json
├── next.config.* (ou équivalent)
├── .env.example
├── public/
└── src/
    ├── app/                    # App Router (Next.js) ou pages/
    │   ├── layout.tsx
    │   ├── page.tsx
    │   ├── (auth)/
    │   ├── folders/
    │   ├── documents/
    │   ├── offices/
    │   ├── users/
    │   ├── roles/
    │   ├── admin/
    │   ├── my-account/
    │   └── ...
    ├── components/
    │   ├── layout/              # Header, sidebar, breadcrumb
    │   ├── ui/                  # Design system (Button, Input, Table, Modal…)
    │   └── domain/              # Composants métier (FolderCard, DocumentList…)
    ├── design-system/           # Tokens, thème par défaut
    │   ├── tokens/
    │   ├── theme.ts
    │   └── index.ts
    ├── api/                     # Client API (appels backend docv)
    │   ├── client.ts            # Instance HTTP, intercepteurs, erreurs
    │   ├── auth.ts
    │   ├── folders.ts
    │   ├── documents.ts
    │   ├── screen-config.ts     # Chargement config écrans/actions
    │   └── ...
    ├── i18n/                    # Structure + textes par défaut (fr, en)
    │   ├── keys.ts
    │   ├── fr.json
    │   └── en.json
    ├── stores/                  # État global (context ou store)
    ├── hooks/                   # useAuth, useFolders, useScreenConfig…
    ├── utils/                   # Helpers (format, validation si pas WASM)
    └── types/                   # Types TS alignés contrats back

4.2 Règles front

• Un seul client API : tous les appels passent par le client docv-back (pas d’URL ancrage ni IA côté front).
• Paramétrage : chargement de la config écrans/actions (et options) au login ou au changement d’office ; affichage des menus et boutons selon cette config ; pas de listes d’écrans/actions en dur.
• i18n : clés structurées ; textes par défaut dans docv ; pas de texte en dur dans l’UI.
• Design system : tokens (couleurs, typo, espacements) et thème par défaut ; composants réutilisables pour enso (surcharges possibles).
• Accessibilité : ARIA, contraste, clavier (référence docs/SCREENS_AND_FUNCTIONS_MAP.md et règles projet).

---

5. Code partagé (docv-shared, docv-core)

5.1 docv-shared (Rust, natif + WASM)

• Contenu : validation de champs (email, longueur, format), formatage (dates, montants), constantes métier (codes erreur, limites), règles métier pures sans I/O.
• Usage back : dépendance Rust classique (natif).
• Usage front : build WASM (wasm-pack), import depuis le front pour réutiliser la même logique (validation formulaire, formatage affichage).
• Place : docv/docv-shared/ ; consommée par docv-back et docv-front (et éventuellement enso-back, enso-front).

5.2 docv-core (TypeScript, optionnel)

• Contenu : types et contrats API (DTOs, réponses paginées), constantes partagées (codes erreur, clés i18n de base). Peut être généré depuis OpenAPI (docv-back) pour garder les contrats alignés.
• Usage : importé par docv-front et enso-front pour typage et appels API.
• Place : docv/docv-core/ ; pas de logique métier lourde (celle-ci reste dans docv-shared/WASM ou dans les services back).

---

6. Paramétrage (écrans, actions, options)

• Stockage : tables (ou entités) screen_config, action_config et tables dédiées pour les options (workflow, types de documents, etc.) + system_configuration pour les feature flags et options globales. Référence : docs/features/PARAMETRAGE_ECRANS_ACTIONS.md.
• Résolution : service dédié (ex. parametrage_service) qui fusionne plateforme → office → type de dossier → rôle → préférence utilisateur ; exposé au front via des endpoints du type GET /screen-config, GET /action-config (et éventuellement GET /me/preferences).
• Back : les handlers qui renvoient des listes d’écrans ou d’actions (pour le menu, les boutons) s’appuient sur ce service ; les middlewares d’auth peuvent enrichir le contexte avec les permissions résolues.
• Front : chargement de la config au démarrage ou au changement d’office ; rendu conditionnel des routes et des boutons selon la config ; pas de liste en dur.

---

7. Sécurité

• Authentification : session ou JWT ; renouvellement et déconnexion gérés par le back.
• Login par défaut docv : docv fournit un système de login par défaut (identifiant / mot de passe, session ou JWT, choix d’office actif) pour tous les types de membres : rôles des offices, membres des dossiers, droits par ressource. enso utilise ce login docv tel quel (aucune implémentation auth spécifique requise dans le périmètre actuel).
• Autorisation : matrice rôle × ressource × action ; vérification dans les services ou middleware avant toute opération sensible.
• CSRF : token CSRF sur les requêtes mutantes (formulaires, POST/PUT/DELETE) ; middleware back pour vérification.
• Secrets : aucun secret en front ; URLs et clés API (ancrage, IA) uniquement en back (variables d’environnement ou config serveur).
• Entrées : validation côté back (et optionnellement côté front via docv-shared WASM) ; pas de confiance aveugle au client.

---

8. Gestion des erreurs et logging

• Back : types d’erreur typés (AppError, AuthError, NotFound, ValidationError) ; impl IntoResponse pour un format JSON cohérent ; logging structuré (niveau, contexte, pas de données sensibles).
• Front : le client API transforme les réponses d’erreur en erreurs typées ; affichage utilisateur via i18n (messages génériques ou clés d’erreur) ; pas de fallback silencieux.
• Clients externes : erreurs ancrage/IA remontées avec contexte ; journalisées ; pas de continuation silencieuse.

---

9. Build et exécution

• docv-back : cargo build, cargo run ; migrations au démarrage ou cargo run -- migrate ; variables d’environnement via .env ou env.
• docv-front : npm run build, npm run dev ; variables d’environnement pour l’URL du backend (ex. NEXT_PUBLIC_API_URL).
• docv-shared : cargo build (natif) et wasm-pack build --target web (ou équivalent) pour le front ; le front importe le pkg/ généré.
• Ordre de build : docv-shared (natif + WASM) → docv-back (dépend docv-shared) ; docv-front (dépend docv-shared pkg si WASM, et docv-core si présent).

---

10. Dépendances et flux de données

• docv ne dépend pas d’enso.
• Données : le front envoie des requêtes au back ; le back lit/écrit la BDD et appelle les API ancrage/IA ; les réponses repassent par le back vers le front.
• Paramétrage : la config (écrans, actions, options) est lue depuis la BDD par le back et servie au front ; les mises à jour se font via les endpoints admin (back uniquement).

---

11. Références

• Architecture globale : docs/ARCHITECTURE_DOCV_ENSO.md
• Plan de réalisation : docs/PLAN_REALISATION_DOCV_ENSO.md
• Cartographie écrans et actions : docs/SCREENS_AND_FUNCTIONS_MAP.md
• Paramétrage : docs/features/PARAMETRAGE_ECRANS_ACTIONS.md
• Référentiel écrans et actions : docs/features/REFERENTIEL_ECRANS_ACTIONS.md
• Description technique d’implémentation (par zone) : docs/features/implementation/README.md
• Spécifiques enso : docs/features/SPECIFIQUES_PROJETS.md
• Grands principes IA : docs/features/IA_GRANDS_PRINCIPES.md