# Dossier d'Architecture Nautile

(reprise du dossier 1.0 disponible ici : https://gitlab.insee.fr/Individus-et-logements/nautile/nautile-documentation/-/blob/master/Architecture/dossier-architecture-Nautile.odt)

> Ce document est versionné par Git sur Gitlab, les dates de modifications sont donc implicites aux différentes versions.

> La version hackmd est disponible ici (en attendant l'intégration plantUML de gitlab
## 1) Présentation générale de l'application

L'application Nautile (nouvelle application utilisée pour le tirage des individus et des logements dans les enquêtes) a pour objet de tirer les échantillons des enquêtes ménages hors EEC. Ce tirage se fait dans une base de sondage logement ou bien une base de sondage individus (selon l'unité statistique choisie par l'enquête) que l'application doit permettre de maintenir à jour (re charger les bases chaque année avec des données actualisées).

Les bases de sondage sont constituées à partir de données fiscales enrichies qui sont fournies à l'application Nautile par l'intermédiaire de Fidéli. Ces données fiscales permettent d'obtenir un minimum d'informations sociales, démographiques et fiscales sur les individus et sur les logements à enquêter. Ces informations ont plusieurs usages : vérifier la qualité des bases et la représentativité des échantillons, faire des tirages stratifiés et permettre le repérage des logements pour les enquêtes en face à face.

La mise à jour des bases de sondage comprend également le marquage des logements et/ou des individus qui ont déjà été interrogés lors d'une enquête précédente afin de ne pas réinterroger deux fois le même individu sur une enquête ménage. Ce marquage doit pouvoir être reporté d'une année sur l'autre car la disjonction entre les échantillons doit être valable sur plusieurs années.

Le tirage des échantillons doit respecter le découpage en Unités Primaires du territoire et se faire dans des Unités Primaires présélectionnées dans le cas d'enquêtes en face à face. Nautile est donc capable de réaliser des tirages dans ses bases de sondage d'échantillons respectant cette contrainte et d'autres comme le respect d'allocations prédéfinies ou bien une stratification.

Afin de permettre la détermination de la charge de travail annuelle des enquêteurs, Nautile permet de calculer des allocations prévisionnelles pour chaque enquêteur pour l'année à venir sur des enquêtes qui seront tirées dans la prochaine base de sondage.

Les allocations prévisionnelles et les fichiers échantillons définitifs sont transmis à Opale par un système à automatiser le plus possible. Nautile alimente aussi d'autres clients à partir des échantillons tirés : tableaux récapitulatifs pour les DEM, échantillons complets pour les CPOS...
Enfin l'application Nautile permet l'impression des Fiches Adresses à partir des échantillons tirés. Cela se fait au travers d'un flux entre Nautile et une application d'éditique : Crabe.

On peut donc distinguer quatre domaines fonctionnels pour l'application Nautile :
1. Gérer les bases de sondage
2. Gérer les plans de sondage
3. Diffuser les données pour la collecte sous forme de Fiches adresses
4. Imprimer les fiches adresses

Il apparaît que ces 4 domaines recouvrent deux grandes fonctionnalités :
1. Sélectionner des individus et/ou des logements pour des enquêtes (domaines 1 et 2)
2. Créer et diffuser les Fiches Adresses correspondant aux individus et/ou logements sélectionné (domaines 3 et 4).

La grande fonctionnalité 2 (Créer et diffuser les Fiches Adresses) s’avère être en lien avec le cycle de vie de la Fiche Adresse et les nombreux applications et acteurs qui interviennent dans ce cycle de vie. L’outil visé par cette étude devrait donc être en mesure de fournir à cet éco système applicatif les fonctions CREATE et READ du CRUD de la FA. Néanmoins, la complexité et les grosses évolutions à venir dans l’éco système applicatif autour de la FA invite à la prudence et à traiter cette fonctionnalité dans un outil séparé pour préserver le cœur de métier de Nautile (le tirage d’échantillon) et laisser du temps supplémentaire au besoin pour se préciser.

Ainsi la fonctionnalité 2 sera traitée dans l’outil Crabe (Centre de ressources Applicatives pour les besoins des enquêtes). Cet outil sera interfacé avec Nautile pour pouvoir y récupérer les données nécessaires à la constitution des fiches adresses d’après les informations figurant dans les échantillons.

Les principaux enjeux pour l'application sont alors :
- assurer une bonne réception des données Fideli
- Reporter les marquages logements et / ou individus d'une année sur l'autre
- Automatiser les circuits de livraison d'échantillons
- Imprimer efficacement les FA
- Arriver à temps pour remplacer Octopusse
- Permettre de tirer des logements ou bien des individus suivant les différentes modalités de tirage spécifiées
- Prendre en compte nativement les contraintes du NCEE
- Être prête à prendre en compte les contraintes du multimode

NB : Le projet Nautile a d'autres objectifs que la seule réalisation de l'application :
- mener efficacement les tests de l'application
- constituer et tires les unités primaires (enjeux m'éthodologiques et organisationnels) probablement en coordination avec les secteurs emploi

## 2) Architecture fonctionnelle

L’architecture fonctionnelle positionne les acteurs de l’application, les principales fonctions, les regroupements par sous-système ainsi que les contraintes et exigences associées au projet. Ce niveau d’architecture n’est pas particulier à une technologie. Il définit ce qui doit être fait, et non comment cela doit être fait.

### 2.1) Description des Acteurs

Bien que l'application ne soit utilisée que par une seule catégorie d'utilisateurs, on peut distinguer plusieurs rôles répondant aux besoins de différents acteurs :
- `Expert sondage` : Il est chargé de tirer des échantillons satisfaisant aux exigences des enquêtes. A cet effet, il alimente la base de sondage, veille à sa qualité et tire les échantillons.
- `Crabe` : Crabe est une application cliente de Nautile qui prend en entrée les allocations et les échantillons produits par Nautile. Elle les fournit ensuite sous forme de fiches adresse a Opale.
- `DEM` : les DEM en régions sont clientes du système pour récupérer les fiches adresses papier (on considère dans ce cas que la chaîne d'impression fait partie du système) et les tableaux de comptage résultant des tirages.
- `MOAE` : il s'agit d'autres utilisateurs qui auront la possibilité de récupérer des données en sortie de Nautile (fichier échantillon complet par exemple)
- `Fidéli`/`Relief`/`Résil`: Un autre acteur essentiel interagit avec l'application, non pas en tant que client mais en tant que fournisseur. Fidéli est le système qui produit les fichiers individus et logements alimentant les bases de sondage Nautile. Au delà d'une application, Fidéli est un système faisant intervenir l'applicatif pour traiter les fichiers fiscaux reçus par l'Insee ainsi que d'autres acteurs chargés d'enrichir ces fichiers (DMRG en ce qui concerne les données géographiques?)

### 2.2) Fonctions de l’application

Le diagramme de cas d'utilisation ci-après décrit le périmètre de l'application.

@startuml
left to right direction
skinparam monochrome true
actor "Expert sondage" as eps
actor "Crabe" as crabe
package Fideli/Relief/RESIL{
     usecase "Affecter les logements aux UP" as UC1
}
package Nautile {
    package "Gérer la base de sondage" {

    package "Gérer une campagne annuelle" {
        usecase "Créer une campagne annuelle" as Cam
        usecase "Supprimer une campagne annuelle" as  Cam2
        }
        package "Disposer d'une base logements/individus pour une année"{
            usecase "Importer une base" as GX2
            usecase "Marquer les unités" as D1
            usecase "Démarquer les unités" as D2
            usecase "Calculer des statistiques sur les livrables"  as GX10
            usecase "Marquer les logements neufs" as GX7
            usecase "Valider un livrable"  as GX8
        }
}
    package "Gérer les plans de sondage" {
        package "Gérer les éditions d'enquête"{
            usecase "Créer une enquête" as E
            usecase "Créer une édition d'enquête" as EE
        }
        package "Gérer le paramétrage du tirage d'une edition d'enquête"{
            usecase "Définir la stratification d'une édition d'enquête" as stratif
            usecase "Définir les unités primaires d'une édition d'enquête et leurs poids" as UP
            usecase "Calculer des statistiques pour valider un paramétrage " as statStratifUp
        }
        package "Gérer les allocation d'une edition d'enquête"{
            usecase "Définir les allocations d'une édition d'enquête" as alloc
            usecase "Calculer des statistiques pour valider un jeu d'allocation " as allocValid
            usecase "Gérer les habilitations de Crabe sur un jeu d'allocation " as allocCrabe
        }
         package "Gérer les échantillons d'une edition d'enquête"{
            usecase "Charger un échantillon" as importEch
             usecase "Tirer un échantillon" as tirageEch
             usecase "Calculer des statistiques pour valider un échantillon" as validEch
             usecase "Supression échantillon " as suppressionEch
             usecase "Gérer les habilitations de Crabe sur un échantillon" as crabeEch
        }
        }
    package "Diffuser les données pour la collecte" {
        usecase "Récuperer les allocations provisoires dans Crabe " as allocCrabeRecev
    usecase "Récuperer les éditions enquêtes dans Crabe " as editionCrabeRecev
   usecase "Récuperer les enquêtes dans Crabe " as enqueteCrabeRecev
        usecase "Récuperer les échantillons dans Crabe " as echCrabeRecev
   }

}
    skinparam usecase {
    backgroundColor Yellow
    }
eps --> UC1
eps ----> Cam
eps ----> Cam2
eps ----> GX2
eps ----> D1
eps ----> D2
eps ----> GX10
eps --> GX7
eps --> GX8
eps --> E
eps --> EE
eps --> stratif
eps --> UP
eps --> statStratifUp
eps --> alloc
eps --> allocValid
eps --> allocCrabe
eps --> importEch
eps --> tirageEch
eps --> validEch
eps --> importEch
eps --> suppressionEch
eps --> crabeEch
crabe --> allocCrabeRecev
crabe --> editionCrabeRecev
crabe --> enqueteCrabeRecev
crabe --> echCrabeRecev
@enduml

On a inclus dans ce diagramme un cas d'utilisation pour l'affectation des logements aux unité primaires (UP) alors que cette fonctionnalité ne devrait pas faire partie du périmètre de Nautile (le traitement devrait être pris en charge par le processus Fidéli). Néanmoins le cette fonctionnalité répond au besoin de l'expert sondage.

Le reste des cas d'utilisation correspond bien au périmètre de l'application Nautile et sont regroupés suivant les 4 grands domaines fonctionnels de Nautile eux-mêmes parfois divisés en sous-domaines. En voici la liste hiérarchisée :
#### Gérer la base de sondage
Toutes les fonctionnalités qui permettent de tenir à jour des bases de sondage pour y effectuer des tirages => Application Nautile :ocean: :
- Gérer une campagne annuelle : Cas d'utilisation pour créer et supprimer des campagnes annuelles qui sont le support des bases de sondage :
- Créer une campagne annuelle : Préalable à l'importation des fichiers Fidéli
- Supprimer une campagne annuelle : Deux ou trois années après son utilisation, une campagne annuelle est supprimée, avec les bases de sondage associées. Ce CU devra décrire en détail ce qu'il faut supprimer et dans quel ordre. Il faudra aussi garder les échantillons tirés.
- Disposer d'une base logement et d'une base individus pour une année : Toutes les fonctionnalités permettant de tenir à jour les données des bases de sondage une fois qu'on dispose de la campagne annuelle : les besoins principaux sont les mêmes qu'on soit avec des individus ou bien des logements, donc ce sont les mêmes CU mais qui pourraient donner lieu à des fonctionnalités différentes selon qu'on est avec la base individus ou bien avec la base logement.
- Importer une base : Lire les données des fichiers fournis par Fideli et les écrire dans le système informatique Nautile
- Marquer les unités : Recopier les marquages de la base de sondage de l'année précédente dans la nouvelle base : chaque unité élogement ou individu) de la novuelle base correspondant à unité de l'ancienne base au sens d'un identifiant longitudinale de l'unité.
- Etablir des statistiques : sortir des restitutions prédéterminées (spécifiques à la nature de la base de sondage) avec l'objectif (commun) de juger de la qualité statistique de la base nouvelle importée.
- Marquer les logements neufs : L'objectif est de tirer des logements neufs (ou bien certainement les individus de ces logements dans le cas de la base individus) et de les marquer pour que ces logements ne soient pas sur-représentés.
- Valider une base : Si tout va bient : passer l'état de la base à Validée pour indiquer qu'on peut y faire des tirages.
- Démarquer les unités : Si besoin en important un fichier avec des identifiants d''unités, on peut démarquer ces unités si on manque d'unités disponibles pour le tirage dans une base donnée.
- Charger un échantillon externe pour marquage des unités statistiques de la base de sondage

#### Gérer les plans de sondage

C'est le coeur de l'application Nautile :ocean:
- Gérer les éditions d'enquêtes :
▪ Créer une enquête : Créer une enquête (Panel Srcv, Camme, …) qui correspond à une série d'opérations statistiques au sens de RMéS : c'est une donnée longitudinale qui permet de faire correspondre entre elles des éditions d'enquêtes qui sont millésimées.
- Créer une édition d'enquête (Srcv 2016, EEC T1 2017, …) : correspond à une opération statistique au sens de RMéS. Cet objet permettra de porter une demande de tirage qui contient toutes informations pour faire le tirage pour l'opération statistique en question.
- Gérer les paramètres du tirage d'une édition d'enquête : Compléter les éléments de la demande de tirage.
- Définir la stratification d'une édition d'enquêtes : Au sein des paramètres de tirage, décrire des expressions qui ont pour objet de partitionner la population en strates
- Définir les UP d'une édition d'enquête et leurs poids : Charger un fichier contenant les UP et des poids (0 si on souhaite ne pas utiliser une UP). Le chargement de ce fichier n'est pas indispensable pour effectuer le tirage (on peut utiliser les poids par défaut des UP).
- Valider : Valider que les paramètres saisis sont cohérents. Notamment que la stratification réaliser bien une partition de la population. Après cette validation, on peut lancer un tirage.
- Gérer les allocations d'une édition d'enquête : Le NCEE oblige à fournir une estimation du nombre de FA à collecter par UP pour toute l'année à venir : cette estimation se fait à partir des bases de sondage n-1 et permet d'établir les planning des enquêteurs. A partir de là, les tirage durant l'année doivent se faire sous contrainte de respect de ces allocations fournies auparavant : on les indique à Nautile à travers un fichier à intégrer.
- Déterminer les allocations d'une édition d'enquête : Produire un fichier avec les allocations pour Opale
- Valider les allocations d'une édition d'enquête : Intégrer un fichier contenant les allocations à prendre en compte pour le tirage.
- Gérer l'échantillon d'une édition d'enquête : Tirer l'échantillon puis le laisser vivre sa vie.
- Tirer un échantillon : Pour une édition d'enquête, réaliser le tirage suivant tous les paramètres et contraintes définies dans la demande de tirage associée.
- Valider : Valider que le tirage effectué est correct.
- Supprimer un échantillon : Dans de rares cas, il est nécessaire de supprimer un échantillon validé et de procéder à nouveau au tirage.
#### Diffuser les données pour la collecte :
Domaine de Nautile qui comprend les fonctionnalités de diffusion des résultats des tirages à ses clients.=> outil Crabe :crab:
- Récupérer les allocations provisoires : l'acteur Opale (c'est bien lui qui porte le besoin c'est lui qui a besoin des allocations) récupère les allocations d'une opération statistique dans Nautile.
- Récupérer l'échantillon définitif : l'acteur Opale récupère l'échantillon avec un ensemble de FA identifiées pour chaque enquêteur avec les informations et le format demandés par Opale
- Récupérer l'échantillon complet d'une opération statistique : toutes les lignes avec toutes les colonnes
> #### Imprimer les FA :
>Domaine qui comprend les fonctionnalités d'édition des FA :=> outil Crabe :crab:
>- Editer toutes les FA : édition massive de toutes les FA d'une opération statistique
>- Editer une FA : rééditer une FA à la demande
>- Imprimer les FA d'un échantillon externe : Import d'un échantillon externe dans Crabe pour impression des FA.

> Cette partie a été séparée du reste

**NB : Bien qu'ayant des acteurs, on peut envisager de traiter chacun de ces cas d'utilisation en batch pour des questions de performance. Néanmoins l'acteur reste à l'initiative du déclenchement du batch.**

### 2.3) Regroupement des fonctions en sous-systèmes fonctionnels

#### 2.3.1) Définition des sous-systèmes fonctionnels

On a deux systèmes fonctionnels qui cohabitent :
- Nautile :ocean:
- Crabe :crab:

> Le flux de données va uniquement dans le sens Nautile → Crabe : Nautile se trouve toujours en amont de Crabe dans le processus qui conduit à l’impression des FA d’une enquête.

skinparam shadowing true
skinparam monochrome true
left to right direction
scale max 2048 width
package "Référentiels autres "{
    node "Référentiels géographiques" as R1
    node "Référentiels d'unités primaires" as R2
    node "Référentiels d'enquête" as R3
}
package "Fideli/Relief/RESIL"{
    database "Fichiers pour Nautile avec Logements preaffectés aux up" as F1
}
package Nautile as NAUT{
    database "Bases de sondage"  as BS
    component "Gérer les bases de sondage" as GBS
    component "Gérer les plans de sondage" as GPS
}
package "Experts Nautile"{
frame "Fichier des poids de sondage" as FPS
frame "Fichier des allocations" as FDA
frame "Fichier echantillon externe " as FECH
frame "Fichier Marquage " as FDEM
frame "Fichier Demarquage " as FMAR
"EXPERT SONDAGE" as ES
}
package "Services Transverses Informatiques"{
    node "Authentification Keycloak" as KC
    node "Service d'envoi de mail SPOC" as SPOC
    node "Service de soumission de tâches SST" as SST
    folder "Applishare" as Applishare
} 

frame "Fichiers d'alimentation des bases" as FAB

frame "Echantillon Expert Nautile" as ECHEN
frame "Allocations Crabe" as ACRABE
frame "Echantillon Crabe" as ECHCRABE

"CRABE" as crabe

R1 ----> GBS
R2 ----> GBS
FDEM ----> GBS
FMAR ----> GBS
GBS <--> BS
GPS <--> BS
GBS --> GPS
ES ----> GBS
ES ----> GPS
R2 ----> GPS
R3 ----> GPS
FPS ----> GPS
FDA ---> GPS
FECH ----> GPS
ES ---> FPS
ES ---> FDA
ES ---> ECHEN
ES ---> ACRABE
ES ---> ECHCRABE
NAUT -> KC
NAUT -> SPOC
NAUT -> SST
NAUT -> ECHEN
NAUT -> ACRABE
NAUT -> ECHCRABE
crabe -> ACRABE
crabe -> ECHCRABE
NAUT -> Applishare
ES -> Applishare
F1 -> FAB
FAB -> GBS
skinparam component {
    backgroundColor<<static lib>> lightBlue
    backgroundColor<<shared lib>> Green
}
skinparam fab{
    backgroundColor Yellow
}
skinparam node {
    borderColor Green
    backgroundColor Yellow
    backgroundColor<<shared node>> Magenta
}
skinparam database{
    BackgroundColor<<nautile>> LightGreen
    BackgroundColor Aqua
}

## 3) Interactions avec des applications de l’Insee

### 3.0) Schéma simplifié global des liens entre Nautile et d'autres applications INSEE

@startuml
skinparam shadowing true
skinparam monochrome true
left to right direction
scale max 2048 width

[Nautile-IHM] as NautileIHM
[Nautile-API] as NautileAPI
[Nautile-BATCH] as NautileBATCH
[BDD Postgres] as bdd
[Crabe] as Crabe
[SPOC] as  SPOC
[SST] as  SST
[Keycloak] as  kc
[Rundeck] as  Rundeck
[FIDELI/RELIEF/RESIL] as donneesfiscales
interface "Recuperation echantillon" as echcrabe
interface "Recuperation allocation" as alloccrabe
interface "envoi mail" as envmail
interface "authentification" as auth
Crabe - echcrabe
Crabe -  alloccrabe
echcrabe --> NautileAPI
alloccrabe --> NautileAPI
NautileIHM --> NautileAPI
NautileAPI ---> SST
NautileAPI - envmail
envmail ---> SPOC
SST -> Rundeck
Rundeck -> NautileBATCH
NautileBATCH -> bdd
NautileAPI -> bdd
donneesfiscales ..> bdd : chargement par dump
NautileAPI <-> auth
NautileIHM <-> auth
auth <-> kc
@enduml

### 3.1) Interactions avec des applications Métier de l'INSEE

#### Fidéli/Relief/RESIL
Pour fournir des fichiers 1 ou 2 fois par an (format à définir) : un fichier avec les logements (base logement) puis un fichier avec les individus (base individus).

Peut être d'abord une version incomplète puis une version complète avec toutes les informations de localisation... suivant les contraintes calendaires.
• Fichier logements : 50 millions de lignes d'une vingtaine de variables
• Fichier individus : 70 millions de lignes d'une quinzaine de variables.

#### Référentiels géographiques divers ou d'unités primaires

A voir pour valider certaines données issues de Fidéli.

- Environ quelques milliers de validations lors de chaque intégration de données de Fidéli

> Pour l'instant la partie unité primaire n'est pas integré dans une chaine applicative

#### RMéS :

Compatibilité du modèle, mais pas d'utilisation du référentiel.

Cible :
- 1 échange pour chaque tirage ou chaque création d'opération statistique : volume négligeable.

#### Crabe :crab: :

Nautile envoie vers Crabe les informations sur les unités sélectionnées après chaque tirage validé dans Nautile :

- quelques dizaines de milliers de lignes pour chaque tirage avec vingt à trente variables. Ce même flux devrait être utilisé pour fournir un fichier complet de l’échantillon à l’expert sondage (et au concepteur d’enquêtes?)
- les fichiers d'allocations définis pour les enquêtes

> Opale : Client qui réceptionne de Crabe dans un premier temps les allocations prévisionnelles de FA par ZAE puis dans un deuxième temps un échantillon définitif suivant un format de fichier plat avec séparateur bien défini.
• Allocations provisoires : fichier plat de quelques dizaines de milliers de lignes avec sept variables
• Fichiers définitifs : quelques dizaines de milliers de lignes par opération statistique avec une vingtaine de colonnes.

### 3.2) Interactions avec des applications pour rendre le service à l'INSEE

#### SST :
Le SST ou Service de Soumission des Tâches est un service permettant d'ordonnancer des tâches Rundeck, il est maintenu a l'INSEE. L'usage est très important dans l'application Nautile où, les traitement nécessitant plus de 100 secondes de temps de calcul sont conçus comme asynchrones et passent donc par un processus d'envoi Batch.

#### Keycloak :
Nautile utilise une authentification OIDC, qui s'appuie en interne sur Keycloak.

#### SPOC :
API d'envois de mails centralisés, SPOC est utilisé pour apporter un retour aux utilisateurs lorsqu'ils envoient des traitements nécessitant des contrôles.

#### Applishare :

Comme précisé dans l'architecture initiale, Nautile prend en entrée une certaine quantité de fichiers, qui sont déposé sur un repertoire que l'application partage avec ses utilisateurs. Ce dépôt se fait soit directement, soit par envoi de données sur le tomcat et copie sur le repertoire.