Monorepo VitaKYC — structure et conventions

Repo : vitakyc-platform/ (Gradle multi-projects). Distinct du repo vitakyc-docs (cette doc) déployé via la pipeline .gitlab-ci.yml que tu lis.

Ce document fixe la structure du monorepo applicatif VitaKYC : où vont les services, les libs, les ressources d’infra, comment activer un module, quelles conventions suivent les nouveaux développements.

1. Layout

vitakyc-platform/
├── settings.gradle.kts             // active les modules au fur et à mesure
├── build.gradle.kts                // conventions root (Kotlin JVM 21, Detekt, Spotless)
├── gradle/
│   ├── libs.versions.toml          // version catalog (Kotlin 2.0, Ktor 2.3, ...)
│   └── wrapper/
├── tools/
│   ├── detekt-config.yml
│   └── ci/                          // scripts CI partagés
├── platform/                        // services transverses (auth, tenant, audit, webhook)
│   ├── auth-svc/                    // ✅ actif — façade OIDC Keycloak + step-up MFA
│   ├── tenant-svc/                  // ✅ actif — provisioning multi-tenant
│   ├── audit-svc/                   // ✅ activé sprint 2 — audit log append-only signature chaînée HMAC (cf ADR-036)
│   └── webhook-svc/                 // ⏳ à activer
├── shared/                          // libs réutilisées par plusieurs services
│   ├── auth-client-jvm/             // ✅ actif — JWT verifier (Keycloak JWKS)
│   ├── observability-jvm/           // ✅ activé sprint 1 — OpenTelemetry + Micrometer/Prometheus + MDC (cf ADR-035)
│   ├── audit-client-jvm/            // ✅ activé sprint 2 — client lib audit (1 ligne/service, outbox local + retry, anti-PII guard) (cf ADR-036)
│   ├── api-contracts/               // ⏳ types DTO partagés cross-svc
│   └── kotlinx-utils/               // ⏳
├── modules/                         // modules métier KYC (un par domaine)
│   ├── form-engine-jvm/             // ✅ activé sprint 0 — lib pure (DSL form, evaluator, validator, JSON canonique)
│   ├── form-designer-svc/           // ✅ activé sprint 2 — Ktor publish/activate, valide cpsPaths via cps-svc avant publish, FormDefinition (cf ADR-027)
│   ├── mrz-svc/                     // ✅ activé sprint 0 — Ktor service exposant le parser MRZ ICAO 9303
│   ├── risk-engine-jvm/             // ✅ activé sprint 2 — lib pure (DSL Risk Matrix RBA, evaluator pur, model cards) (cf ADR-025)
│   ├── risk-matrix-svc/             // ✅ activé sprint 2 — Ktor publish/activate/evaluate, valide cpsPaths via HTTP cps-svc avant publish (cf ADR-025)
│   ├── cps-svc/                     // ✅ activé sprint 2 — Client Profile Schema multi-tenant (validate symbols, deprecate, consumers) (cf ADR-026)
│   ├── sanctions-matcher-jvm/       // ⏳
│   ├── sanctions-svc/               // ⏳
│   ├── case-mgmt-svc/               // ✅ activé sprint 2 — workflow agent L1/L2/L3 (assign, review, approve, reject, escalate) (cf ADR-029)
│   ├── tx-monitoring-svc/           // ⏳
│   ├── aml-rules-engine-jvm/        // ⏳
│   ├── bio-svc/                     // ✅ activé sprint 2 (MVP synchrone) — orchestrateur biométrique : OCR + MRZ + doc-auth + liveness + face-match + cross-checks (cf ADR-028 ; Temporal V2)
│   └── notification-svc/            // ⏳
├── apps/                            // applications front (à venir)
├── frontend/                        // (vide pour l'instant)
├── infra/                           // resources d'infra
│   ├── docker-compose.dev.yml       // ✅ stack dev complet (9 services)
│   ├── observability/               // ✅ overlay docker-compose : Tempo, Prometheus, Loki, Grafana, Alertmanager, OTel Collector (cf ADR-035)
│   ├── postgres/init-multi-db.sh
│   ├── keycloak/realm-template/vitakyc-saas-realm.json
│   ├── back-office-web/nginx.conf
│   ├── helm/                        // ⏳ charts Kubernetes (prod)
│   └── k8s/                         // ⏳ manifests K8s
└── scripts/                         // utilitaires dev (lint, release, ...)

2. Conventions de nommage

Suffixe	Type	Exemples
`-svc`	Service Ktor déployable (microservice avec endpoints HTTP)	`auth-svc`, `tenant-svc`, `mrz-svc`, `form-designer-svc`
`-jvm`	Lib Kotlin pure (sans réseau, sans DB), réutilisable cross-svc	`form-engine-jvm`, `risk-engine-jvm`, `auth-client-jvm`
`platform/*`	Services transverses utilisés par tous les modules métier	`auth-svc`, `tenant-svc`, `audit-svc`
`modules/*`	Modules métier KYC (un par bounded context)	`form-designer-svc`, `bio-svc`, `case-mgmt-svc`
`shared/*`	Libs partagées entre modules ET platform	`auth-client-jvm`, `api-contracts`

3. Activer un module

3 étapes.

3.1 Décommenter dans `settings.gradle.kts`

//include(":modules:form-engine-jvm")
include(":modules:form-engine-jvm")

3.2 Créer `build.gradle.kts` du module

Lib pure (*-jvm) :

plugins {
    alias(libs.plugins.kotlin.serialization)
}

dependencies {
    implementation(libs.kotlinx.serialization.json)
    implementation(libs.kotlinx.coroutines.core)
    implementation(libs.slf4j.api)
    testImplementation(libs.bundles.testing)
}

Service Ktor (*-svc) :

plugins {
    alias(libs.plugins.kotlin.serialization)
    alias(libs.plugins.ktor)
    application
}

application {
    mainClass.set("io.vitakyc.<domain>.ApplicationKt")
}

dependencies {
    implementation(libs.bundles.ktor.server)
    implementation(libs.kotlinx.serialization.json)
    implementation(libs.kotlinx.coroutines.core)
    implementation(libs.logback.classic)
    testImplementation(libs.bundles.testing)
}

ktor { fatJar { archiveFileName.set("<svc-name>.jar") } }

3.3 Sources

Layout standard d’un service Ktor :

modules/<svc-name>/
├── build.gradle.kts
├── Dockerfile                             // multi-stage Gradle 8.10/JDK 21 → temurin alpine
└── src/main/kotlin/io/vitakyc/<domain>/
    ├── Application.kt                      // main + module wiring
    ├── config/AppConfig.kt                 // env vars
    ├── plugins/Plugins.kt                  // serialization, monitoring, status pages, routing
    ├── routes/<X>Route.kt                  // un fichier par regroupement d'endpoints
    └── domain/                             // model + business logic
└── src/main/resources/
    └── logback.xml
└── src/test/kotlin/...                     // Ktor `testApplication { ... }`

4. Stack Docker Compose dev

Lancement :

cd vitakyc-platform/infra
docker compose -f docker-compose.dev.yml up -d

Service	Image	Port	Usage
`postgres`	`postgres:16-alpine`	5432	bases multiples : `vitakyc_auth`, `vitakyc_tenant`, `vitakyc_audit`, `keycloak`, `temporal`
`keycloak`	`keycloak:25.0`	8180	IdP, realm `vitakyc-saas` importé au boot
`kafka`	`apache/kafka:3.7.0`	9092 / 29092	mode KRaft single-node
`opensearch`	`opensearchproject/opensearch:2.17`	9200	sanctions screening, recherche full-text
`vault`	`hashicorp/vault:1.17`	8200	KMS + signatures Ed25519 (mode dev)
`temporal`	`temporalio/auto-setup:1.25`	7233	orchestration workflows
`temporal-ui`	`temporalio/ui:2.32`	8088	console Temporal
`minio`	`minio/minio:RELEASE.2024-09-22`	9000 / 9001	stockage S3-compat documents
`auth-svc`	`registry.../auth-svc:develop`	8080	OIDC façade
`tenant-svc`	`registry.../tenant-svc:develop`	8082	provisioning
`mrz-svc`	`registry.../mrz-svc:develop`	8083	parser MRZ ICAO 9303
`back-office-web`	`nginx:alpine`	8081	SPA front statique

Health checks : tous les services exposent /health (Ktor) ou healthcheck Docker dédié (Postgres pg_isready, MinIO mc ready, etc.).

Reset complet :

docker compose -f docker-compose.dev.yml down -v   # WARNING: efface tous les volumes

5. État d’activation au sprint 0

Type	Module	Statut	Tests
Platform	`auth-svc`	✅ actif	5 routes tests
Platform	`tenant-svc`	✅ actif	2 routes tests
Module	`form-engine-jvm`	✅ activé sprint 0	18/18 verts (DSL, evaluator, validator, JSON canonique)
Module	`mrz-svc`	✅ activé sprint 0	23/23 verts (18 parser + 5 route HTTP)
Shared	`auth-client-jvm`	✅ actif	(utilisé par auth-svc)

Tous les autres modules sont listés dans settings.gradle.kts mais commentés — activés au fur et à mesure des sprints.

6. Pipeline CI/CD applicative

Pipeline GitLab vitakyc-platform/.gitlab-ci.yml (en construction) — pour chaque service <svc>-svc :

gradle :modules:<svc>-svc:test — tests JUnit + Ktor test host
gradle :modules:<svc>-svc:buildFatJar — fat jar
docker build -f modules/<svc>-svc/Dockerfile -t registry.e-vitalis.com/root/vitakyc-platform/<svc>-svc:$CI_COMMIT_SHA .
docker push vers le registry interne
(manuel) Helm release sur cluster K8s prod

Les images consommées par infra/docker-compose.dev.yml sont taguées :develop — alignées sur la branche main du repo.

7. Smoke test rapide

# Build le fat jar localement (gradle download le JDK 21)
./gradlew :modules:mrz-svc:buildFatJar

# Lance le service sur le port 8083
HTTP_PORT=8083 ~/.gradle/jdks/eclipse_adoptium-21-amd64-linux.2/bin/java \
  -jar modules/mrz-svc/build/libs/mrz-svc.jar &

# Health check
curl http://localhost:8083/health
# → {"status":"ok","service":"mrz-svc"}

# Parse une MRZ TD3 ICAO standard
curl -X POST -H "Content-Type: application/json" \
  -d '{"mrz":"P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<\nL898902C36UTO7408122F1204159ZE184226B<<<<<10","strict":false}' \
  http://localhost:8083/v1/mrz/parse
# → {"format":"TD3","document_number":"L898902C3","surname":"ERIKSSON",...,"checksum_score":1.0}

8. Roadmap d’activation des modules

Sprint	Modules à activer	Priorité
S0 ✅	`form-engine-jvm`, `mrz-svc`	bootstrap
S1	`cps-svc` (registry CPS), `form-designer-svc` (consomme form-engine + cps), `risk-engine-jvm`	flux Form Designer end-to-end
S2	`risk-matrix-svc`, `sanctions-matcher-jvm`, `sanctions-svc`	risk + screening
S3	`case-mgmt-svc`, `notification-svc`, `audit-svc`	back-office compliance
S4	`tx-monitoring-svc`, `aml-rules-engine-jvm`	AML transactionnel
S5	`bio-svc` (orchestrateur biométrique), `webhook-svc`	biométrie + livraison events

Chaque activation de module suit le pattern §3 et clôture sur :

Tests verts
Build Dockerfile fonctionnel
Service ajouté à infra/docker-compose.dev.yml
Update de cette page (statut + count tests)

9. Références

ADRs structurants : ADR-001 Temporal, ADR-002 multi-tenant RLS, ADR-005 stockage MinIO, ADR-027 Form engine
POCs originaux (avant migration) : poc-form-designer, poc-mrz-parser
Spec moteur Form Designer : Form Designer engineering
Pipeline biométrique : Biometric pipeline

Document tenu à jour à chaque activation de module. Sprint 0 livré le 2026-04-26.