Documentation Crystal

Architecture Technique

Vue d'ensemble

Le système Crystal est conçu selon une architecture en couches avec séparation claire des responsabilités. Cette structure permet une grande flexibilité et une maintenance simplifiée.

Architecture en couches du système Crystal et interactions avec les systèmes externes

Architecture système

Crystal s'intègre dans un écosystème plus large, interagissant avec plusieurs systèmes externes pour créer une plateforme complète de mise en relation des entrepreneurs et des partenaires financiers.

Composants du système

  • Crystal Core : Système central gérant les données, les API et la logique métier
  • Plateforme PDE : Source des données d'entrepreneurs
  • Institutions Financières : Partenaires offrant des services aux entrepreneurs
  • Application Mobile Agents : Interface pour les agents de terrain
  • Système d'authentification : Service de gestion des identités et permissions

Architecture applicative

Crystal est basé sur une architecture Quarkus avec une séparation claire entre les couches d'API, de service et d'accès aux données.

Caractéristiques techniques

  • Framework Quarkus : Framework Java optimisé pour les microservices et les environnements cloud-native
  • Programmation Réactive : Utilisation du modèle réactif avec Mutiny et Panache Reactive pour une meilleure scalabilité et efficacité
  • Reactive PostgreSQL Client : Accès non-bloquant à la base de données pour un débit plus élevé
  • API RESTful Réactives : Conception des endpoints API avec RESTEasy Reactive

Configuration Quarkus

  • Format YAML : Configuration centralisée dans application.yml
  • Liquibase : Gestion des migrations de base de données
  • JWT : Authentification basée sur JSON Web Tokens
  • SmallRye OpenAPI : Documentation API automatique avec Swagger
  • Quarkus Mailer : Service d'envoi d'emails
  • CORS : Configuration pour permettre les requêtes cross-origin
  • Stockage : Gestion des fichiers uploadés dans des répertoires configurables

Structure du code source

  • Controllers : Points d'entrée de l'API organisés par domaine fonctionnel
    • security/ - Gestion de l'authentification et des autorisations
    • admin/ - Administration du système
    • enterprise/ - Gestion des entreprises partenaires
    • external/ - Intégrations avec systèmes externes (PDE)
  • Core : Noyau fonctionnel du système
    • business/ - Logique métier
    • services/ - Services applicatifs
    • models/ - Modèles transversaux (Pagination, ApiResponse, etc.)
    • filestorage/ - Gestion du stockage de fichiers
    • requests/ - Objets de transfert de données pour les requêtes
    • exceptions/ - Gestion centralisée des exceptions
    • database/ - Accès aux données et persistance
    • configs/ - Configuration de l'application
  • Database : Organisation de la couche d'accès aux données
    • models/ - Modèles de données persistants
    • repositories/ - Accès aux données avec patterns Repository
    • mappers/ - Conversion entre entités et DTOs
    • dtos/ - Objets de transfert de données
    • enums/ - Types énumérés pour la cohérence des données
  • Utilities : Fonctions utilitaires réutilisables

Flux de données principaux du système Crystal

Flux d'intégration avec PDE

Le processus d'intégration avec la Plateforme Digitale pour l'Entrepreneuriat (PDE) est une composante clé du système.

Étapes du flux

  1. L'entrepreneur s'inscrit sur la plateforme PDE
  2. L'entrepreneur donne son consentement pour partager ses informations
  3. PDE transmet les données de l'entrepreneur à Crystal via API
  4. Crystal stocke les données et les rend disponibles aux partenaires
  5. Les partenaires financiers contactent l'entrepreneur
  6. Crystal enregistre l'interaction entre partenaires et entrepreneurs

Flux de processus terrain

Les agents de terrain jouent un rôle crucial dans l'enrichissement des données et l'accompagnement des entrepreneurs.

Processus complet de qualification terrain des entrepreneurs

📋
Planification des visites

L'agent identifie les entrepreneurs à visiter dans sa zone géographique

🚶
Visite terrain

L'agent rencontre l'entrepreneur et collecte des informations supplémentaires

📱
Saisie des données

Les informations sont saisies dans l'application mobile et synchronisées

🔄
Enrichissement du profil

Le profil de l'entrepreneur est complété avec les nouvelles données

📊
Qualification

L'entrepreneur est qualifié selon les besoins des partenaires financiers

Sécurité et protection des données

La sécurité est une préoccupation majeure pour le système Crystal, qui manipule des données personnelles et financières sensibles.

Mesures de sécurité

  • Authentification : Authentification à deux facteurs pour tous les comptes administrateurs et partenaires
  • Autorisation : Système de rôles et permissions granulaires basé sur Quarkus Security
  • Chiffrement : Chiffrement des données sensibles en transit (TLS) et au repos
  • Logging : Journalisation complète des actions critiques pour audit et détection d'intrusion
  • Validation : Validation stricte des entrées pour prévenir les injections

Authentification par JWT avec SmallRye

Le système utilise SmallRye JWT, une implémentation de la spécification MicroProfile JWT Auth pour Quarkus.

  • Tokens JWT : Authentification sans état via JSON Web Tokens signés
  • Modèle à double token : Utilisation de tokens d'accès (courte durée) et de rafraîchissement (longue durée)
  • Gestion des sessions : Suivi des connexions actives via la table admin_session
  • Révocation : Possibilité d'invalider des tokens en cas de compromission
  • Permissions RBAC : Contrôle d'accès basé sur les rôles définis dans les claims JWT
  • Signature et vérification : Utilisation de clés asymétriques pour la génération et validation des tokens

Flux d'authentification

  1. L'utilisateur s'authentifie avec ses identifiants (email/mot de passe)
  2. Le système valide les identifiants et génère un token d'accès et un token de rafraîchissement
  3. Le client utilise le token d'accès pour les requêtes API (en-tête Authorization)
  4. Quand le token d'accès expire, le client utilise le token de rafraîchissement pour en obtenir un nouveau
  5. Lors de la déconnexion, les tokens sont invalidés en base de données

Modèle de Données

Le modèle de données de Crystal est conçu pour gérer efficacement les relations entre entrepreneurs, partenaires financiers et agents terrain.

Diagramme Entité-Relation des principales tables du système

Structure principale du modèle

  • Les comptes utilisateurs (account) sont liés à des profils personnels (person)
  • Les agents de terrain (field_agent) sont liés à des entreprises partenaires (enterprise)
  • Les entrepreneurs PDE (pde_entrepreneur) sont visités par des agents terrain lors des visites (field_visit)
  • Chaque interaction est tracée et conservée dans le système

Pour une description détaillée du modèle de données, consultez la documentation du modèle de données.