Dépôt Numérique

Application de dépôt automatisé de documents métier.

Le projet est initialisé en monorepo avec pnpm et Turbo. Il contient actuellement :

• apps/api : API NestJS ;
• apps/web : frontend Angular ;
• apps/worker : workers BullMQ ;
• packages/database : schéma, migrations, seed et client Prisma partagés ;
• docs : documentation VitePress ;
• sso : simulateur SSO local avec Keycloak SAML et OpenLDAP ;
• turbo.json : configuration des tâches monorepo ;
• pnpm-workspace.yaml : déclaration des workspaces pnpm.

Prérequis

• Node.js, via nvm.
• pnpm 11.8.0.
• Docker et Docker Compose, pour les services techniques locaux.

La version Node attendue est indiquée dans .nvmrc.

nvm use

Si la version n'est pas installée :

nvm install

Installation

Depuis la racine du dépôt :

pnpm install

Si pnpm demande d'approuver des scripts de build :

pnpm approve-builds

Puis relancer :

pnpm install

Installer les hooks Git locaux avec Lefthook :

pnpm exec lefthook install

La commande pnpm install exécute aussi le script prepare, qui installe Lefthook automatiquement. La commande ci-dessus reste utile si les hooks ne sont pas présents après un clone ou un changement d'environnement.

Créer les fichiers d'environnement locaux :

cp .env.example .env
cp apps/api/.env.example apps/api/.env
cp packages/database/.env.example packages/database/.env
cp apps/worker/.env.example apps/worker/.env

Le fichier racine configure PostgreSQL, Redis, MinIO et le simulateur SSO local Keycloak/OpenLDAP/phpLDAPadmin. Le fichier de l'API définit API_PORT et NODE_ENV, celui de Prisma fournit DATABASE_URL, et celui du worker définit WORKER_PORT et NODE_ENV. Ces fichiers ne doivent pas être commités.

Lancer le projet

Le développement local utilise deux terminaux afin de séparer les services Docker des applications.

Dans un premier terminal, démarrer les services techniques et attendre leur disponibilité :

pnpm infra:dev

Dans un second terminal, lancer toutes les tâches de développement déclarées dans les workspaces :

pnpm dev

pnpm infra:dev lance PostgreSQL, Redis, MinIO, OpenLDAP, phpLDAPadmin et Keycloak avec Docker Compose. pnpm dev lance l'API, le frontend, le worker et la documentation avec Turbo.

Pour lancer l'API NestJS, le frontend Angular et le worker BullMQ sans démarrer l'infrastructure Docker ni la documentation :

pnpm apps:dev

Services exposés en développement :

• API NestJS : http://localhost:3000
• Frontend Angular : http://localhost:4200

SSO Local

Le projet utilise en développement un simulateur SSO SAML local. OpenLDAP contient l'annuaire de test avec les utilisateurs, leurs rôles et leur rattachement métier (bureauIGC). Keycloak est configuré comme fournisseur d'identité SAML et expose ces attributs à l'application.

Les rôles applicatifs simulés sont :

• DEPOT_NUMERIQUE:ADMINISTRATEUR_GENERAL
• DEPOT_NUMERIQUE:ADMINISTRATEUR_REGIONAL
• DEPOT_NUMERIQUE:ADMINISTRATEUR_LOCAL
• DEPOT_NUMERIQUE:AGENT

L'arborescence LDAP locale simule notamment la DSJ, les cours d'appel, les tribunaux judiciaires, les CPH au niveau des cours d'appel et les tribunaux de proximité sous leur tribunal judiciaire. Les comptes de test et les attributs SAML exposés sont documentés dans docs/keycloak.md, avec le détail du simulateur dans sso/README.md.

Lancer Un Service Applicatif

API NestJS :

pnpm api:dev

Frontend Angular :

pnpm web:dev

Documentation VitePress :

pnpm docs:dev

Worker BullMQ :

pnpm worker:dev

Commandes utiles

Les commandes suivent une nomenclature simple :

• pnpm <tâche> lance la tâche sur tous les workspaces concernés via Turbo.
• pnpm <workspace>:<tâche> lance la même tâche sur un workspace précis.
• Les workspaces disponibles sont api, web, worker, docs et database.
• Les commandes dev sont des serveurs persistants et ne sont pas mises en cache par Turbo.

Exemples :

pnpm build
pnpm api:build
pnpm web:build
pnpm docs:build
pnpm database:build
pnpm worker:build

Lister les packages du workspace :

pnpm -r list --depth -1

Compiler tous les packages qui exposent une tâche build :

pnpm build

Compiler un workspace précis :

pnpm api:build
pnpm web:build
pnpm docs:build

Lancer les tests :

pnpm test

Lancer les tests d'un workspace précis :

pnpm api:test
pnpm web:test
pnpm worker:test

Le test du worker couvre le processor de la queue de démonstration sans nécessiter Redis. Il n'y a pas de commande docs:test, car la documentation n'expose pas de script de test.

Lancer le lint Biome :

pnpm lint

Lancer le lint sur un workspace précis :

pnpm api:lint
pnpm web:lint
pnpm docs:lint
pnpm database:lint
pnpm worker:lint

Formater le code avec Biome :

pnpm format

Formater un workspace précis :

pnpm api:format
pnpm web:format
pnpm docs:format
pnpm database:format
pnpm worker:format

Vérifier le formatage sans modifier les fichiers :

pnpm format:check

Vérifier le formatage d'un workspace précis :

pnpm api:format:check
pnpm web:format:check
pnpm docs:format:check
pnpm database:format:check
pnpm worker:format:check

Vérifier le formatage, le lint et les règles Biome :

pnpm check

Vérifier un workspace précis :

pnpm api:check
pnpm web:check
pnpm docs:check
pnpm database:check
pnpm worker:check

Vérifier les types TypeScript :

pnpm typecheck

Vérifier les types d'un workspace précis :

pnpm api:typecheck
pnpm web:typecheck
pnpm database:typecheck
pnpm worker:typecheck

Il n'y a pas de commande docs:typecheck, car VitePress est vérifié via pnpm docs:build.

Corriger automatiquement ce qui peut l'être :

pnpm check:fix

Corriger automatiquement un workspace précis :

pnpm api:check:fix
pnpm web:check:fix
pnpm docs:check:fix
pnpm database:check:fix
pnpm worker:check:fix

Détecter les dépendances inutilisées et le code mort :

pnpm knip

Lancer tous les contrôles qualité avant une PR ou un push important :

pnpm verify

Cette commande enchaîne pnpm check, pnpm knip, pnpm typecheck et pnpm test.

Base de données

Le workspace @depot-numerique/database centralise Prisma pour l'API et les futurs workers. PostgreSQL stocke les métadonnées métier et les références MinIO ; les fichiers binaires restent dans MinIO.

Commandes principales :

pnpm database:build
pnpm database:lint
pnpm database:format
pnpm database:format:check
pnpm database:check
pnpm database:check:fix
pnpm database:typecheck
pnpm database:generate
pnpm database:validate
pnpm database:migrate:create --name description
pnpm database:migrate:dev --name description
pnpm database:migrate:deploy
pnpm database:migrate:status
pnpm database:seed
pnpm database:studio

Le script pnpm database:studio force Prisma Studio sur http://localhost:5555.

Le workspace database n'a pas encore de commande de test dédiée.

Les migrations créées en développement sont versionnées dans packages/database/prisma/migrations. En recette et en production, la CI/CD applique ces mêmes migrations avec pnpm database:migrate:deploy sur la base de l'environnement concerné. pnpm database:migrate:create --name description génère et permet de relire le SQL sans l'appliquer.

Le modèle Prisma représente les utilisateurs SSO et les structures judiciaires hiérarchisées : la cour d'appel, ses juridictions et leurs éventuelles sous-juridictions. Les services sont rattachés à une structure et sont créés localement par les administrateurs autorisés. Un utilisateur distingue sa structure de travail (workStructureId) de son éventuel périmètre d'administration (adminStructureId) ; son service est rattaché à sa structure de travail. Chaque document référence obligatoirement son utilisateur créateur. Les comptes sont désactivés plutôt que supprimés afin de conserver cet historique. Le périmètre d'administration est déduit du rôle et du niveau de la structure administrée : un administrateur régional voit la cour d'appel et ses descendants, tandis qu'un administrateur local placé sur une cour d'appel ne gère que les services de cette cour.

Le seed crée la cour d'appel de Douai, les tribunaux judiciaires de Lille, Arras et Douai, ainsi que le tribunal de proximité de Tourcoing rattaché à Lille. La cour d'appel et les trois tribunaux judiciaires reçoivent les services baj, bog, jaf et jap, identifiés par leur slug et accompagnés d'un libellé complet. Les structures utilisent des codes SSO uniques sur huit chiffres, par exemple 00000001 pour la cour et 00000002 pour le tribunal de Lille. Ce jeu de données est destiné au développement et aux tests.

La documentation détaillée se trouve dans docs/database.md.

Qualité de code

Le projet utilise une configuration centralisée à la racine du monorepo.

• Biome : formatage et lint.
• Knip : détection des dépendances inutilisées, exports inutilisés et fichiers morts.
• Lefthook : hooks Git locaux.
• Commitlint : validation des messages de commit au format Conventional Commits.

Avant de commit, Lefthook lance Biome sur les fichiers staged et réajoute automatiquement les fichiers corrigés.

Au commit, Lefthook lance aussi Commitlint sur le message de commit.

Avant un push, Lefthook lance en parallèle pnpm check, pnpm knip, pnpm typecheck et pnpm test.

Tester le dernier commit :

pnpm commitlint

Commandes principales :

pnpm format
pnpm format:check
pnpm lint
pnpm check
pnpm check:fix
pnpm verify
pnpm typecheck
pnpm knip
pnpm prepare

Docker

Docker Compose lance les services techniques utilisés en développement local.

Services disponibles :

• PostgreSQL : base de données métier ;
• Redis : cache et backend BullMQ ;
• MinIO : stockage des documents ;
• OpenLDAP : annuaire local simulant les utilisateurs et rattachements SRJ ;
• phpLDAPadmin : interface graphique locale pour inspecter l'annuaire LDAP ;
• Keycloak : fournisseur d'identité SAML local branché sur OpenLDAP ;
• plus tard, images séparées pour l'API, le frontend et les workers.

Les versions d'images sont volontairement fixées dans docker-compose.yml. Ne pas utiliser latest pour les services d'infrastructure.

Versions locales actuelles :

• PostgreSQL : postgres:17.10-bookworm
• Redis : redis:7.4.9-bookworm
• MinIO : minio/minio:RELEASE.2025-09-07T16-13-09Z
• OpenLDAP : osixia/openldap:1.5.0
• phpLDAPadmin : osixia/phpldapadmin:0.9.0
• Keycloak : quay.io/keycloak/keycloak:26.6.4

Dependabot surveille les mises à jour Docker Compose, GitHub Actions et npm/pnpm via .github/dependabot.yml.

Créer un fichier .env local à partir de l'exemple si nécessaire :

cp .env.example .env

Le fichier .env ne doit pas être commit. Il est ignoré par Git.

Lancer tous les services techniques :

pnpm infra:dev

Lancer uniquement PostgreSQL :

docker compose up -d postgres

Lancer uniquement Redis :

docker compose up -d redis

Lancer uniquement MinIO :

docker compose up -d minio

Lancer uniquement Keycloak et attendre sa disponibilité :

docker compose up -d --wait keycloak

Lancer uniquement l'annuaire LDAP et son interface graphique :

docker compose up -d --wait openldap phpldapadmin

Keycloak importe le realm depot-numerique depuis sso/keycloak/realm.json et lit les utilisateurs dans OpenLDAP. Les données LDAP locales sont initialisées depuis sso/openldap/schema et sso/openldap/ldif. Après une modification du realm, forcer la recréation du conteneur :

docker compose up -d --force-recreate --wait keycloak

Après une modification du schéma ou du LDIF OpenLDAP, il faut recréer les volumes OpenLDAP locaux pour réimporter l'annuaire. Cette instance utilise start-dev, HTTP, une base H2 éphémère et des mots de passe publics de démonstration. Elle est strictement réservée au développement local. Consulter la documentation SSO SAML local pour les comptes, rôles, attributs SAML et procédures de test.

Vérifier leur état :

docker compose ps

Afficher les logs :

docker compose logs -f

Arrêter les services :

docker compose down

Supprimer aussi les volumes locaux :

docker compose down -v

Attention : docker compose down -v supprime les données PostgreSQL, Redis et MinIO locales. Les données Keycloak sont éphémères et sont recréées depuis le fichier du realm.

Accès locaux par défaut :

• PostgreSQL : localhost:5432
• Redis : localhost:6379
• MinIO API : http://localhost:9000
• MinIO Console : http://localhost:9001
• Keycloak : http://localhost:8080
• OpenLDAP : ldap://localhost:389
• phpLDAPAdmin : http://localhost:8081

Les identifiants locaux sont définis dans .env.

Documentation

La documentation technique est dans docs/ et utilise VitePress.

Commandes disponibles :

pnpm docs:dev
pnpm docs:build
pnpm docs:preview

Le package documentation est déclaré comme workspace @depot-numerique/docs dans docs/package.json.

La configuration VitePress utilise base: '/depot-numerique/' pour une publication GitHub Pages sur ce dépôt.

Structure actuelle

apps/
  api/    # API NestJS
  web/    # Frontend Angular
docs/     # Documentation VitePress
packages/
  database/ # Schéma, migrations, seed et client Prisma

Stack

• Monorepo : Turbo
• Gestionnaire de paquets : pnpm
• Backend : NestJS
• Frontend : Angular
• Documentation projet : VitePress
• Base de données : PostgreSQL
• ORM : Prisma
• Queue et cache : BullMQ, Redis
• Stockage fichiers : MinIO
• SSO local : Keycloak, OpenLDAP, phpLDAPAdmin
• Automatisation web : Playwright
• Documentation API : Swagger / OpenAPI
• Conteneurisation : Docker, Docker Compose
• Qualité de code : Biome, Knip, Lefthook, Commitlint
• CI/CD : GitHub Actions
• Secrets : Vault
• Supervision : Prometheus, Grafana