PD-13 — Initialiser projet NestJS avec structure modulaire¶

Métadonnées¶

• Epic : PD-186 — BACKEND-CORE
• Type : Foundation / Infrastructure Task
• Priorité : Critique (bloquante)
• Story Points : 8

1. Contexte¶

Le backend ProbatioVault constitue le cœur applicatif du système :

• authentification Zero-Knowledge (SRP-6a),
• orchestration cryptographique,
• gestion documentaire WORM,
• journalisation probatoire,
• ancrage blockchain.

Une architecture NestJS modulaire, stricte et industrialisée est indispensable pour garantir :

• la maintenabilité long terme,
• la sécurité by design,
• la scalabilité technique et organisationnelle,
• la conformité aux standards ProbatioVault.

Cette User Story pose la fondation technique de tout le backend. Aucune autre PD backend ne peut démarrer sans celle-ci.

2. Objectifs¶

• Initialiser un projet NestJS 10+ avec TypeScript en mode strict.
• Mettre en place une architecture modulaire cible (auth, crypto, documents, audit, storage, jobs…).
• Configurer les outils de qualité : ESLint, Prettier, Jest, SonarQube.
• Déployer une CI/CD GitLab complète (lint → tests → build → qualité).
• Fournir une base sécurisée, testable et observable.

3. Portée¶

Inclus¶

• Création du projet NestJS via CLI
• Configuration TypeScript stricte
• Mise en place ESLint / Prettier / SonarQube
• Configuration Jest (unit / integration / e2e)
• Dockerfile multistage + docker-compose dev
• Pipeline GitLab CI/CD
• Structure modulaire complète
• Documentation initiale (README, CONTRIBUTING, ADR)

Hors périmètre¶

• Implémentation métier détaillée (PD suivantes)
• Schémas DB et RLS (PD-14+)
• Logique SRP-6a complète

4. Architecture cible¶

probatio-vault-backend/
├── src/
│   ├── main.ts
│   ├── app.module.ts
│   ├── config/
│   ├── common/
│   ├── modules/
│   │   ├── auth/
│   │   ├── crypto/
│   │   ├── documents/
│   │   ├── audit/
│   │   ├── storage/
│   │   └── jobs/
│   └── database/
├── test/
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── Dockerfile
├── docker-compose.yml
├── .gitlab-ci.yml
├── tsconfig.json
├── .eslintrc.js
├── .prettierrc
├── sonar-project.properties
├── README.md
├── CONTRIBUTING.md
└── docs/adr/

5. Spécifications techniques¶

5.1 Stack technique¶

• Node.js : 20.x LTS
• Framework : NestJS 10.x
• Langage : TypeScript 5.x (strict)
• DB : PostgreSQL (via TypeORM ultérieurement)
• Queue : Redis + BullMQ
• Tests : Jest
• Qualité : ESLint, Prettier, SonarQube

5.2 TypeScript¶

• Mode strict activé
• Aucun any implicite
• Paths aliases configurés (@/, @modules/*, etc.)

5.3 Qualité & sécurité¶

• ESLint avec règles sécurité (eslint-plugin-security)
• Prettier intégré
• SonarQube avec Quality Gate strict

5.4 CI/CD GitLab¶

• Stages : lint → test → build → quality
• Analyse SonarQube obligatoire
• Build Docker multistage

5.5 Conteneurisation¶

• Dockerfile multistage
• Image finale non-root
• Healthcheck /health

5bis. Diagrammes Mermaid¶

5bis.1 Pipeline CI/CD — Diagramme de séquence¶

Flux multi-service du pipeline GitLab (cf. §5.4, §7 CI/CD).

sequenceDiagram
    participant Dev as Développeur
    participant GL as GitLab Runner
    participant ES as ESLint / Prettier
    participant Jest as Jest
    participant Nest as NestJS Build
    participant Sonar as SonarQube
    participant Docker as Docker Registry

    Dev->>GL: git push
    activate GL

    rect rgb(240, 248, 255)
        Note over GL,ES: Stage 1 — lint
        GL->>ES: eslint --max-warnings 0
        ES-->>GL: 0 erreur critique (§7 Infrastructure)
        GL->>ES: prettier --check
        ES-->>GL: Conforme (§5.3)
    end

    rect rgb(240, 255, 240)
        Note over GL,Jest: Stage 2 — test
        GL->>Jest: jest --coverage
        Jest-->>GL: Couverture >= 85% (§7 Qualité)
    end

    rect rgb(255, 248, 240)
        Note over GL,Nest: Stage 3 — build
        GL->>Nest: nest build (TypeScript strict)
        Nest-->>GL: 0 warning TS (§5.2, §11 DoD)
        GL->>Docker: docker build --multistage
        Docker-->>GL: Image non-root + healthcheck (§5.5)
    end

    rect rgb(248, 240, 255)
        Note over GL,Sonar: Stage 4 — quality
        GL->>Sonar: sonar-scanner
        Sonar-->>GL: Quality Gate PASS (§5.3)
    end

    GL-->>Dev: Pipeline verte (§11 DoD)
    deactivate GL

5bis.2 Bootstrap applicatif — Diagramme de séquence¶

Séquence de démarrage NestJS et résolution des modules (cf. §4 Architecture cible, §6 Modules).

sequenceDiagram
    participant Main as main.ts
    participant App as AppModule
    participant Cfg as ConfigModule
    participant Common as CommonModule
    participant Mod as Modules métier
    participant Health as HealthController

    Main->>App: NestFactory.create(AppModule)
    activate App

    App->>Cfg: import ConfigModule.forRoot()
    Cfg-->>App: Variables validées (Joi)

    App->>Common: import CommonModule
    Note right of Common: Guards, Filters,<br/>Interceptors, Pipes (§6 common)

    App->>Mod: import AuthModule, CryptoModule,<br/>DocumentsModule, AuditModule,<br/>StorageModule, JobsModule
    Note right of Mod: Chaque module :<br/>module + service + test (§6)

    App->>Health: register /health, /health/db, /health/ready
    App-->>Main: Application prête

    Main->>Main: app.listen(PORT)
    deactivate App

5bis.3 Health check — Diagramme d'états¶

États du endpoint /health (cf. §5.5 Healthcheck, §7 Infrastructure).

stateDiagram-v2
    [*] --> Starting : NestFactory.create()

    Starting --> Healthy : Bootstrap OK<br/>(tous modules chargés)
    Starting --> Unhealthy : Erreur chargement module

    Healthy --> Degraded : /health/db FAIL<br/>(PostgreSQL indisponible)
    Healthy --> Unhealthy : Erreur critique<br/>(module auth/crypto DOWN)

    Degraded --> Healthy : /health/db OK<br/>(PostgreSQL rétabli)
    Degraded --> Unhealthy : Cascade d'erreurs

    Unhealthy --> Starting : Redémarrage conteneur<br/>(Docker restart policy)

    state Healthy {
        [*] --> Ready
        Ready : /health → 200
        Ready : /health/db → 200
        Ready : /health/ready → 200
    }

    state Degraded {
        [*] --> PartialReady
        PartialReady : /health → 200
        PartialReady : /health/db → 503
        PartialReady : /health/ready → 200
    }

    state Unhealthy {
        [*] --> NotReady
        NotReady : /health → 503
        NotReady : /health/ready → 503
    }

6. Modules à créer (structure minimale)¶

• auth : authentification (SRP-6a, JWT)
• crypto : hash, chiffrement, HKDF
• documents : CRUD documents
• audit : journalisation probatoire
• storage : S3 / Glacier
• jobs : workers BullMQ
• config : configuration centralisée validée
• common : guards, interceptors, filters

Chaque module doit contenir a minima :

• un module NestJS,
• un service,
• un test unitaire initial.

7. Critères d'acceptation¶

Infrastructure¶

• Projet NestJS initialisé (CLI officiel)
• Compilation TypeScript sans warning
• ESLint : 0 erreur critique
• Prettier conforme

Architecture¶

• Tous les modules créés
• Imports cohérents et découplés
• DI NestJS utilisée partout

Qualité & tests¶

• Jest configuré
• ≥ 1 test par module
• Couverture ≥ 85 %

CI/CD¶

• Pipeline GitLab fonctionnel
• SonarQube exécuté avec Quality Gate
• Build Docker OK

Documentation¶

• README complet
• CONTRIBUTING.md présent
• ADR initialisé

8. Dépendances¶

Bloquantes¶

• Aucune

Dépendantes¶

• PD-14 : Configuration PostgreSQL
• PD-15 : Schéma users
• PD-16 : Schéma documents
• Toutes les PD backend suivantes

9. Risques & mitigations¶

10. Livrables¶

• Dépôt backend initialisé
• Structure modulaire complète
• CI/CD opérationnelle
• Dockerfile + docker-compose
• Documentation initiale

11. Definition of Done¶

• Projet NestJS opérationnel
• 0 warning TS / ESLint
• Pipeline verte
• Image Docker build & run OK
• Documentation validée
• Code review approuvée (2 reviewers)